@marver-design/marver 0.11.1 → 0.13.0

package/dist/auth-DdUKeVKt.mjs

@@ -0,0 +1,1150 @@
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createHash, createHmac, randomBytes, scryptSync, timingSafeEqual } from "node:crypto";
+//#region src/server/share.ts
+/**
+* The sharing roster and the ONE resolver (01-sharing §4-5, 04-solution §2.2).
+*
+* `share.json` lives beside `auth.json` on the volume and is the only grant
+* store. `publish.json` (via meta.json `rights`) stays the per-board CEILING;
+* this file holds who was granted what and until when. The resolver is a pure
+* function - blocklist first, then the highest matching grant, then the ceiling
+* clamps - and it is consulted at every door: gate admission, identity
+* provisioning, password sign-in, comment writes, request-access eligibility
+* and SSE re-authorization. One function, so no door can drift.
+*
+* The non-promotion invariant is carried by two mechanics and nothing else:
+* reads always use `min(current ceiling, grant.boardRole[b])`, and every boot
+* re-clamps `boardRole[b] = min(previous ?? assigned, ceiling[b])` - ceilings
+* pull entries down, never up. A later ceiling rise leaves the entry low, which
+* is exactly the condition the owner's re-confirm action raises. No version
+* hashes, no reconcile ceremony.
+*
+* No share.json = pre-migration 0.11 behaviour, exactly. The file is created
+* once at serve boot from the migration matrix (01-sharing §10); until then
+* every caller falls back to the legacy rules it always had. A present but
+* corrupt or malformed file fails CLOSED - a policy typo must deny, never
+* quietly grant the ceiling.
+*/
+var share_exports = /* @__PURE__ */ __exportAll({
+	ceilingsFromRights: () => ceilingsFromRights,
+	commentAllowed: () => commentAllowed,
+	ensureShare: () => ensureShare,
+	entryAllowed: () => entryAllowed,
+	grantFromInviteRedemption: () => grantFromInviteRedemption,
+	loadRequests: () => loadRequests,
+	loadShare: () => loadShare,
+	operativeMode: () => operativeMode,
+	provisionVerdict: () => provisionVerdict,
+	putRequest: () => putRequest,
+	reclampShare: () => reclampShare,
+	reconfirmGrant: () => reconfirmGrant,
+	removeGrant: () => removeGrant,
+	removePrincipalGrants: () => removePrincipalGrants,
+	renamePrincipalGrants: () => renamePrincipalGrants,
+	resolveAccess: () => resolveAccess,
+	resolveRequest: () => resolveRequest,
+	roleMax: () => roleMax,
+	roleMin: () => roleMin,
+	rosterEtag: () => rosterEtag,
+	saveShare: () => saveShare,
+	setBlocked: () => setBlocked,
+	setGeneralMode: () => setGeneralMode,
+	shareFile: () => shareFile,
+	shareState: () => shareState,
+	upsertGrant: () => upsertGrant
+});
+const RANK = {
+	none: 0,
+	view: 1,
+	comment: 2
+};
+const roleMin = (a, b) => RANK[a] <= RANK[b] ? a : b;
+const roleMax = (a, b) => RANK[a] >= RANK[b] ? a : b;
+const shareFile = (dir) => join(dir, "share.json");
+/** meta.json rights → ceilings. `read` publishes at view; `comment` at comment. */
+const ceilingsFromRights = (rights) => Object.fromEntries(Object.entries(rights).map(([b, r]) => [b, r === "comment" ? "comment" : "view"]));
+const ROLES = /* @__PURE__ */ new Set([
+	"none",
+	"view",
+	"comment"
+]);
+const MODES = /* @__PURE__ */ new Set([
+	"private",
+	"password",
+	"public"
+]);
+/** Fail CLOSED on anything malformed: an unknown role string must never rank
+*  above a real one, and a misspelt mode must never open the anonymous door. */
+function validateStore(p) {
+	const bad = (why) => {
+		throw new Error(`share store is malformed (${why}) - refusing to load it. Fix or delete it deliberately.`);
+	};
+	if (p?.version !== 1) bad("version must be 1");
+	if (!MODES.has(p?.general?.mode)) bad(`general.mode "${p?.general?.mode}"`);
+	if (p?.general?.role !== "view") bad("general.role must be \"view\"");
+	if (!Array.isArray(p?.blocked) || p.blocked.some((b) => typeof b !== "string")) bad("blocked must be addresses");
+	if (!Array.isArray(p?.grants)) bad("grants must be an array");
+	for (const g of p.grants) {
+		if (typeof g?.principal !== "string" || !g.principal) bad("grant principal");
+		if (g?.scope !== "canvas" && !(typeof g?.scope === "string" && g.scope.startsWith("board:"))) bad(`grant scope "${g?.scope}"`);
+		if (g?.assigned !== "view" && g?.assigned !== "comment") bad(`grant assigned "${g?.assigned}"`);
+		if (typeof g?.boardRole !== "object" || g.boardRole === null) bad("grant boardRole");
+		for (const r of Object.values(g.boardRole)) if (!ROLES.has(r)) bad(`boardRole value "${r}"`);
+		if (g?.expires !== null && typeof g?.expires !== "string") bad("grant expires");
+	}
+}
+/** Null when no share.json exists (pre-migration) - callers keep legacy rules.
+*  A present-but-unreadable/corrupt/malformed file fails CLOSED. */
+function loadShare(dir) {
+	let raw;
+	try {
+		raw = readFileSync(shareFile(dir), "utf8");
+	} catch (err) {
+		if (err.code === "ENOENT") return null;
+		throw new Error(`share store unreadable (${err.message}) - refusing to treat it as absent`);
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		throw new Error("share store is corrupt JSON - refusing to treat it as absent. Restore it or delete it deliberately.");
+	}
+	validateStore(parsed);
+	return parsed;
+}
+/** Atomic rewrite; expired grants garbage-collect on every write, the same sweep
+*  invites and sessions already ride. 0600 - the roster is a list of addresses.
+*  The request-path cache is refreshed HERE, in-process: the supported setup is
+*  single-instance, so the writer and every reader share this module, and an
+*  mtime tie on a coarse filesystem can never serve a pre-revoke roster. */
+function saveShare(dir, store) {
+	const now = Date.now();
+	store.grants = store.grants.filter((g) => !g.expires || Date.parse(g.expires) > now);
+	const file = shareFile(dir);
+	mkdirSync(dirname(file), { recursive: true });
+	const tmp = `${file}.${randomBytes(6).toString("hex")}.tmp`;
+	const fd = openSync(tmp, "wx", 384);
+	try {
+		writeSync(fd, JSON.stringify(store, null, 2));
+		fsyncSync(fd);
+	} finally {
+		closeSync(fd);
+	}
+	renameSync(tmp, file);
+	cache.set(dir, {
+		mtime: statSync(file).mtimeMs,
+		store
+	});
+}
+const cache = /* @__PURE__ */ new Map();
+function shareState(dir) {
+	const file = shareFile(dir);
+	let mtime = -1;
+	try {
+		mtime = statSync(file).mtimeMs;
+	} catch {}
+	const hit = cache.get(dir);
+	if (hit && hit.mtime === mtime) return hit.store;
+	const store = mtime < 0 ? null : loadShare(dir);
+	cache.set(dir, {
+		mtime,
+		store
+	});
+	return store;
+}
+/** Materialise boardRole entries for a grant, clamped: canvas scope covers every
+*  published board, a board scope exactly its board. Existing entries are kept
+*  (the ratchet) unless the ceiling pulls them down. */
+function materialise(g, ceilings) {
+	const boards = g.scope === "canvas" ? Object.keys(ceilings) : [g.scope.slice(6)];
+	for (const b of boards) {
+		if (!(b in ceilings)) continue;
+		g.boardRole[b] = roleMin(g.boardRole[b] ?? g.assigned, ceilings[b]);
+	}
+}
+/** The boot re-clamp (01-sharing §3.6): atomically, before serving. Ceilings
+*  pull entries down never up; boards new to this build get entries at
+*  min(assigned, ceiling). Entries for boards no longer published are kept -
+*  the ratchet must survive a board leaving and returning. */
+function reclampShare(dir, ceilings) {
+	withLock(dir, () => {
+		const store = loadShare(dir);
+		if (!store) return;
+		for (const g of store.grants) {
+			materialise(g, ceilings);
+			for (const b of Object.keys(g.boardRole)) if (b in ceilings) g.boardRole[b] = roleMin(g.boardRole[b], ceilings[b]);
+		}
+		saveShare(dir, store);
+	}, ".share.lock");
+}
+/**
+* First-boot migration (01-sharing §10): every live 0.11 canvas keeps its exact
+* behaviour. The generated roster is a normal file the owner can read; creating
+* it is logged by the caller. Existing accounts each get a canvas-scoped
+* `comment` grant (clamped per board) because that is precisely what they could
+* do yesterday; general access mirrors the gate the environment configures.
+*/
+function ensureShare(dir, mode, users, ceilings) {
+	return withLock(dir, () => {
+		if (existsSync(shareFile(dir))) return { created: false };
+		const at = (/* @__PURE__ */ new Date()).toISOString();
+		saveShare(dir, {
+			version: 1,
+			general: {
+				mode,
+				role: "view"
+			},
+			blocked: [],
+			grants: users.map((u) => {
+				const g = {
+					principal: normEmail(u.email),
+					scope: "canvas",
+					assigned: "comment",
+					boardRole: {},
+					expires: null,
+					by: "migration",
+					at
+				};
+				materialise(g, ceilings);
+				return g;
+			})
+		});
+		return { created: true };
+	}, ".share.lock");
+}
+/** Upsert a grant (idempotent by principal+scope) and materialise its entries.
+*  Re-granting REPLACES: new assigned, fresh ratchet - the owner just said so.
+*
+*  v1 accepts `scope: "canvas"` ONLY (04-solution §9.4): before read privacy
+*  exists, a board-scoped grant would open the whole bundle while reading as
+*  "just this board" - the schema stays v2-ready, the door refuses. Domain
+*  principals need the identity gate: a canvas that cannot verify addresses
+*  cannot verify domains (01-sharing §4.4), and they ship only together with
+*  the blocklist, which is why creation demands `identityMode`. */
+function upsertGrant(dir, ceilings, input, opts = {}) {
+	if (input.scope !== "canvas") throw new Error("v1 accepts canvas-scoped grants only - board scopes arrive with read privacy (v2)");
+	if (input.principal.startsWith("@") && !opts.identityMode) throw new Error("domain grants need the identity gate - a password canvas cannot verify who holds an address");
+	return withLock(dir, () => {
+		const store = loadShare(dir);
+		if (!store) throw new Error("no share store - the canvas has not booted under v2 yet");
+		const principal = input.principal.startsWith("@") ? input.principal.toLowerCase().trim() : normEmail(input.principal);
+		const now = Date.now();
+		const prior = store.grants.find((g) => g.principal === principal && g.scope === input.scope && live(g, now));
+		const changed = !prior || prior.assigned !== input.assigned;
+		store.grants = store.grants.filter((g) => !(g.principal === principal && g.scope === input.scope));
+		const g = {
+			principal,
+			scope: input.scope,
+			assigned: input.assigned,
+			boardRole: !changed && prior ? { ...prior.boardRole } : {},
+			expires: input.expires ?? null,
+			by: input.by,
+			at: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		materialise(g, ceilings);
+		store.grants.push(g);
+		saveShare(dir, store);
+		return {
+			...g,
+			changed
+		};
+	}, ".share.lock");
+}
+/** Remove every grant held by an exact principal. Ridden by account revocation:
+*  `revokeUser` alone would leave the grant behind, and on an identity canvas
+*  the next sign-in would quietly re-provision the account it just removed. */
+function removePrincipalGrants(dir, email) {
+	withLock(dir, () => {
+		const store = loadShare(dir);
+		if (!store) return;
+		const norm = normEmail(email);
+		const before = store.grants.length;
+		store.grants = store.grants.filter((g) => g.principal !== norm);
+		if (store.grants.length !== before) saveShare(dir, store);
+	}, ".share.lock");
+}
+/** Follow a verified rename: exact grants move to the address the same subject
+*  now holds - the owner granted the person, and the address is a label on
+*  them (docs promise: renames follow the subject). Domain grants never move;
+*  they simply re-evaluate against the new address. A grant already existing
+*  for the new address wins (it is the newer statement of intent). */
+function renamePrincipalGrants(dir, fromEmail, toEmail) {
+	withLock(dir, () => {
+		const store = loadShare(dir);
+		if (!store) return;
+		const from = normEmail(fromEmail), to = normEmail(toEmail);
+		let changed = false;
+		for (const g of store.grants) {
+			if (g.principal !== from) continue;
+			if (store.grants.some((o) => o !== g && o.principal === to && o.scope === g.scope)) continue;
+			g.principal = to;
+			changed = true;
+		}
+		if (changed) {
+			store.grants = store.grants.filter((g) => g.principal !== from);
+			saveShare(dir, store);
+		}
+	}, ".share.lock");
+}
+const domainOf = (email) => normEmail(email).split("@")[1] ?? "";
+const grantMatches = (g, email) => g.principal.startsWith("@") ? g.principal.slice(1) === domainOf(email) : g.principal === normEmail(email);
+const live = (g, now) => !g.expires || Date.parse(g.expires) > now;
+/**
+* The pure resolver. Blocklist first (the only deny), then grants additive
+* (highest wins, read through the boardRole ratchet with the read-time ceiling
+* min), general access contributes `view` when the mode is not Private, and the
+* owner/operator ROLE precedes principal matching exactly as `admin` does today
+* (clamped by the ceiling like everything else - an unpublished board is empty
+* even for the owner).
+*
+* `email: null` is an anonymous caller - someone past a password gate or on a
+* public canvas. They have no principal to match and cannot be blocked (there
+* is no identity to block), which is 01-sharing §3.4 stated as code.
+*
+* `exactOnly` drops domain grants from consideration: the password sign-in
+* door uses it, because domain membership is only meaningful when an identity
+* service verified the address (01-sharing §4.4).
+*/
+function resolveAccess(input) {
+	const { store, ceilings } = input;
+	const email = input.email ? normEmail(input.email) : null;
+	const now = Date.now();
+	const trace = [];
+	const boards = {};
+	if (email && store.blocked.some((b) => normEmail(b) === email)) {
+		for (const b of Object.keys(ceilings)) boards[b] = "none";
+		trace.push({
+			where: "blocklist",
+			role: "none",
+			why: `${email} is blocked - refused everywhere, ahead of every grant`,
+			win: true
+		});
+		return {
+			entry: false,
+			boards,
+			role: "none",
+			trace
+		};
+	}
+	trace.push({
+		where: "blocklist",
+		role: "none",
+		why: email ? "not blocked" : "anonymous - no identity to block",
+		win: false
+	});
+	const matching = email ? store.grants.filter((g) => live(g, now) && grantMatches(g, email) && !(input.exactOnly && g.principal.startsWith("@"))) : [];
+	const anonView = store.general.mode !== "private" ? "view" : "none";
+	let top = "none";
+	for (const b of Object.keys(ceilings)) {
+		let r = "none";
+		if (input.userRole === "owner") r = roleMin("comment", ceilings[b]);
+		for (const g of matching) r = roleMax(r, roleMin(g.boardRole[b] ?? "none", ceilings[b]));
+		r = roleMax(r, roleMin(anonView, ceilings[b]));
+		boards[b] = r;
+		top = roleMax(top, r);
+	}
+	if (input.userRole === "owner") trace.push({
+		where: "role",
+		role: "comment",
+		why: "canvas owner - precedes principal matching",
+		win: true
+	});
+	if (matching.length) {
+		const best = matching.map((g) => `${g.principal} ${g.assigned}${g.expires ? ` until ${g.expires.slice(0, 10)}` : ""}`).join(", ");
+		trace.push({
+			where: "grants",
+			role: top,
+			why: `highest of: ${best}`,
+			win: input.userRole !== "owner"
+		});
+	} else if (email && input.userRole !== "owner") trace.push({
+		where: "grants",
+		role: "none",
+		why: "no matching grant",
+		win: false
+	});
+	if (anonView !== "none") trace.push({
+		where: "general",
+		role: "view",
+		why: `general access is ${store.general.mode} - anyone admitted reads`,
+		win: top === "view" && !matching.length && input.userRole !== "owner"
+	});
+	trace.push({
+		where: "ceiling",
+		role: top,
+		why: "publish.json clamps per board - reads use min(ceiling, boardRole)",
+		win: false
+	});
+	return {
+		entry: RANK[top] >= RANK.view,
+		boards,
+		role: top,
+		trace
+	};
+}
+/** What the gate consults, request-path cheap: is this identified person still
+*  let in at all? Owner always is (someone must administer). Pre-migration
+*  (no store) keeps legacy behaviour: any valid session is gate passage. */
+function entryAllowed(dir, user, ceilings) {
+	const store = shareState(dir);
+	if (!store) return true;
+	if (user.role === "owner") return true;
+	return resolveAccess({
+		email: user.email,
+		userRole: user.role,
+		store,
+		ceilings
+	}).entry;
+}
+/** The comment seam's new internals: may this person write on this board.
+*  Pre-migration keeps today's rule (any signed-in user on a comment board). */
+function commentAllowed(dir, user, board, ceilings) {
+	const store = shareState(dir);
+	if (!store) return ceilings[board] === "comment";
+	if (ceilings[board] !== "comment") return false;
+	return resolveAccess({
+		email: user.email,
+		userRole: user.role,
+		store,
+		ceilings
+	}).boards[board] === "comment";
+}
+/**
+* The provisioning doors' question: may this address be admitted at all.
+* `blocked` beats everything. With ceilings in hand (every real server has
+* them) the answer is the ONE resolver's entry test; without them (bare test
+* harnesses only) it falls back to the materialised entries, which are
+* ceiling-clamped already. `aliases` lets a verified rename count the grants
+* the subject held under its previous address.
+*/
+function provisionVerdict(store, email, opts = {}) {
+	const addresses = [email, ...opts.aliases ?? []].map(normEmail);
+	for (const a of addresses) if (store.blocked.some((b) => normEmail(b) === a)) return "blocked";
+	const now = Date.now();
+	for (const a of addresses) if (opts.ceilings) {
+		if (resolveAccess({
+			email: a,
+			store: {
+				...store,
+				general: {
+					mode: "private",
+					role: "view"
+				}
+			},
+			ceilings: opts.ceilings,
+			exactOnly: opts.exactOnly
+		}).entry) return "granted";
+	} else if (store.grants.some((g) => live(g, now) && grantMatches(g, a) && !(opts.exactOnly && g.principal.startsWith("@")) && Object.values(g.boardRole).some((r) => RANK[r] >= RANK.view))) return "granted";
+	return "none";
+}
+/** An unexpired v1 invite, redeemed after migration, materialises the same
+*  canvas-scoped comment grant an existing account received (01-sharing §10) -
+*  because that is exactly what claiming it would have produced under v1.
+*  A no-op before migration (no store) and on an address already granted. */
+function grantFromInviteRedemption(dir, email, ceilings = {}) {
+	const store = shareState(dir);
+	if (!store) return;
+	const principal = normEmail(email);
+	if (store.grants.some((g) => g.principal === principal && g.scope === "canvas")) return;
+	upsertGrant(dir, ceilings, {
+		principal,
+		scope: "canvas",
+		assigned: "comment",
+		by: "invite"
+	});
+}
+/** The operative general mode: what the environment can actually enforce clamps
+*  what the roster asks for. No gate can only be Public; a password gate cannot
+*  be Public (the password would be theater); an identity gate is Private in v1. */
+function operativeMode(stored, env) {
+	if (env.issuer) return "private";
+	if (env.password) return stored === "private" ? "private" : "password";
+	return "public";
+}
+/** The strong ETag mutations are conditioned on: a hash of the exact stored
+*  roster bytes - share.json AND the pending requests, because approving a
+*  request is a mutation the roster read included, and a replay after any
+*  intervening change (a re-ask, a decline) must fail its precondition. */
+function rosterEtag(dir) {
+	let raw = "";
+	try {
+		raw = readFileSync(shareFile(dir), "utf8");
+	} catch {}
+	let reqRaw = "";
+	try {
+		reqRaw = readFileSync(join(dir, "requests.json"), "utf8");
+	} catch {}
+	return createHash("sha256").update(raw).update("\n").update(reqRaw).digest("hex").slice(0, 32);
+}
+function removeGrant(dir, principal, scope) {
+	withLock(dir, () => {
+		const store = loadShare(dir);
+		if (!store) return;
+		const norm = principal.startsWith("@") ? principal.toLowerCase().trim() : normEmail(principal);
+		const before = store.grants.length;
+		store.grants = store.grants.filter((g) => !(g.principal === norm && g.scope === scope));
+		if (store.grants.length !== before) saveShare(dir, store);
+	}, ".share.lock");
+}
+/** The re-confirm badge's verb: raises ONE board's ratchet entry back to
+*  min(assigned, ceiling) - the only thing that ever raises one (01-sharing §3.6). */
+function reconfirmGrant(dir, ceilings, principal, scope, board) {
+	withLock(dir, () => {
+		const store = loadShare(dir);
+		if (!store) throw new Error("no share store");
+		const norm = principal.startsWith("@") ? principal.toLowerCase().trim() : normEmail(principal);
+		const g = store.grants.find((x) => x.principal === norm && x.scope === scope);
+		if (!g) throw new Error("no such grant");
+		if (!(board in ceilings)) throw new Error("no such board");
+		g.boardRole[board] = roleMin(g.assigned, ceilings[board]);
+		saveShare(dir, store);
+	}, ".share.lock");
+}
+function setGeneralMode(dir, mode) {
+	withLock(dir, () => {
+		const store = loadShare(dir);
+		if (!store) throw new Error("no share store");
+		store.general = {
+			mode,
+			role: "view"
+		};
+		saveShare(dir, store);
+	}, ".share.lock");
+}
+function setBlocked(dir, address, blocked) {
+	withLock(dir, () => {
+		const store = loadShare(dir);
+		if (!store) throw new Error("no share store");
+		const norm = normEmail(address);
+		const has = store.blocked.some((b) => normEmail(b) === norm);
+		if (blocked && !has) store.blocked.push(norm);
+		else if (!blocked && has) store.blocked = store.blocked.filter((b) => normEmail(b) !== norm);
+		else return;
+		saveShare(dir, store);
+	}, ".share.lock");
+}
+const requestsFile = (dir) => join(dir, "requests.json");
+function loadRequests(dir) {
+	try {
+		const p = JSON.parse(readFileSync(requestsFile(dir), "utf8"));
+		const now = Date.now();
+		return Array.isArray(p) ? p.filter((r) => typeof r?.email === "string" && r.exp > now) : [];
+	} catch {
+		return [];
+	}
+}
+function saveRequests(dir, rows) {
+	const file = requestsFile(dir);
+	const tmp = `${file}.${randomBytes(6).toString("hex")}.tmp`;
+	const fd = openSync(tmp, "wx", 384);
+	try {
+		writeSync(fd, JSON.stringify(rows));
+		fsyncSync(fd);
+	} finally {
+		closeSync(fd);
+	}
+	renameSync(tmp, file);
+}
+function putRequest(dir, req) {
+	return withLock(dir, () => {
+		const existing = loadRequests(dir);
+		const fresh = !existing.some((r) => normEmail(r.email) === normEmail(req.email));
+		const at = (/* @__PURE__ */ new Date()).toISOString();
+		const rows = existing.filter((r) => normEmail(r.email) !== normEmail(req.email));
+		rows.push({
+			...req,
+			email: normEmail(req.email),
+			at,
+			exp: Date.now() + 2592e6
+		});
+		saveRequests(dir, rows);
+		return {
+			fresh,
+			at
+		};
+	}, ".share.lock");
+}
+/** Approving adds the grant (canvas-wide in v1 - the dialog says so) and
+*  resolves the row; declining just resolves it, silently to the asker. */
+function resolveRequest(dir, ceilings, email, approve) {
+	const row = loadRequests(dir).find((r) => normEmail(r.email) === normEmail(email));
+	if (!row) return false;
+	if (approve) upsertGrant(dir, ceilings, {
+		principal: row.email,
+		scope: "canvas",
+		assigned: approve.assigned,
+		by: approve.by
+	});
+	withLock(dir, () => {
+		saveRequests(dir, loadRequests(dir).filter((r) => normEmail(r.email) !== normEmail(email)));
+	}, ".share.lock");
+	return true;
+}
+//#endregion
+//#region src/server/auth.ts
+/**
+* Accounts, invites, sessions - the minimal credible implementation,
+* extending the gate's own idiom. No framework: per-user salted scrypt verifiers,
+* opaque session tokens stored hashed, single-use invite links as the identity
+* bootstrap (no email infrastructure anywhere).
+*
+* Password = read, account = comment: everything here concerns accounts only; the
+* shared gate password (serve.ts) remains the outer READ boundary.
+*
+* State lives in MARVER_DATA_DIR as two small JSON files rewritten atomically -
+* users change rarely; the event-log treatment is reserved for comments.
+*/
+var auth_exports = /* @__PURE__ */ __exportAll({
+	CLI_TOKEN_CHARS: () => CLI_TOKEN_CHARS,
+	MIN_CLI_TOKEN: () => 32,
+	attachAvatar: () => attachAvatar,
+	avatarSourceFor: () => avatarSourceFor,
+	canvasSecret: () => canvasSecret,
+	claimInvite: () => claimInvite,
+	cliTokenProblem: () => cliTokenProblem,
+	createInvite: () => createInvite,
+	inviteInfo: () => inviteInfo,
+	issueDeviceSession: () => issueDeviceSession,
+	loadStore: () => loadStore,
+	normEmail: () => normEmail,
+	opaqueId: () => opaqueId,
+	operatorUser: () => operatorUser,
+	ownerName: () => ownerName,
+	provisionFromMarverId: () => provisionFromMarverId,
+	publicUser: () => publicUser,
+	revokeUser: () => revokeUser,
+	sessionIsOperator: () => sessionIsOperator,
+	sessionUser: () => sessionUser,
+	signIn: () => signIn,
+	signOut: () => signOut,
+	updateProfile: () => updateProfile,
+	withLock: () => withLock
+});
+const SCRYPT = {
+	N: 2 ** 15,
+	r: 8,
+	p: 1,
+	keylen: 32,
+	maxmem: 67108864
+};
+const INVITE_TTL = 6048e5;
+const SESSION_TTL = 2592e6;
+const normEmail = (e) => e.trim().toLowerCase();
+const sha256 = (s) => createHash("sha256").update(s).digest("hex");
+const token = () => randomBytes(32).toString("base64url");
+const storeFile = (dir) => join(dir, "auth.json");
+/** Only a MISSING file is an empty store. A present-but-unreadable/corrupt auth.json
+*  must fail CLOSED - treating it as empty would let the owner bootstrap re-run and
+*  a later save overwrite every account. */
+function loadStore(dir) {
+	let raw;
+	try {
+		raw = readFileSync(storeFile(dir), "utf8");
+	} catch (err) {
+		if (err.code === "ENOENT") return {
+			users: [],
+			invites: [],
+			sessions: []
+		};
+		throw new Error(`auth store unreadable (${err.message}) - refusing to treat it as empty`);
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		throw new Error("auth store is corrupt JSON - refusing to treat it as empty. Restore it or delete it deliberately.");
+	}
+	if (!Array.isArray(parsed?.users) || !Array.isArray(parsed?.invites) || !Array.isArray(parsed?.sessions)) throw new Error("auth store has an unexpected shape - refusing to load it");
+	return parsed;
+}
+/** Atomic rewrite (tmp + rename) - a crash mid-write must never lose every account.
+*  0600 throughout: the store holds emails and password verifiers. */
+function saveStore(dir, store) {
+	const file = storeFile(dir);
+	mkdirSync(dirname(file), { recursive: true });
+	const now = Date.now();
+	store.invites = store.invites.filter((i) => i.exp > now);
+	store.sessions = store.sessions.filter((s) => s.exp > now);
+	const tmp = `${file}.${randomBytes(6).toString("hex")}.tmp`;
+	const fd = openSync(tmp, "wx", 384);
+	try {
+		writeSync(fd, JSON.stringify(store, null, 2));
+		fsyncSync(fd);
+	} finally {
+		closeSync(fd);
+	}
+	renameSync(tmp, file);
+}
+/** Cross-process mutex over auth.json's read-modify-write. Within one Node process
+*  the store mutations are already synchronous and atomic; this covers deploy overlap
+*  and any accidental multi-instance run (the supported setup is single-instance) -
+*  without it, a sign-in that loaded a pre-revoke snapshot could rename it back over a
+*  successful revoke. A crashed holder's lock is stolen after 10s; waiting past 5s
+*  fails loudly rather than hanging. */
+function withLock(dir, fn, lockName = ".auth.lock") {
+	mkdirSync(dir, { recursive: true });
+	const lock = join(dir, lockName);
+	const nap = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+	const deadline = Date.now() + 5e3;
+	for (;;) try {
+		closeSync(openSync(lock, "wx"));
+		break;
+	} catch (e) {
+		if (e.code !== "EEXIST") throw e;
+		try {
+			if (Date.now() - statSync(lock).mtimeMs > 1e4) {
+				unlinkSync(lock);
+				continue;
+			}
+		} catch {
+			continue;
+		}
+		if (Date.now() > deadline) throw new Error("auth store is busy - please retry");
+		nap(25);
+	}
+	try {
+		return fn();
+	} finally {
+		try {
+			unlinkSync(lock);
+		} catch {}
+	}
+}
+const findUser = (store, email) => store.users.find((u) => normEmail(u.email) === normEmail(email));
+/** Mint a single-use invite for an email (this IS the allowlist entry - inviting an
+*  address authorizes it). Re-inviting an email replaces its pending invite. The raw
+*  token is returned exactly once; only its hash is stored. */
+/** The owner's display name - public-safe (never the email). Null before claim. */
+function ownerName(dir) {
+	return loadStore(dir).users.find((u) => u.role === "owner")?.name?.trim() || null;
+}
+/** Peek at a live invite: the claim screens show WHO the invite is for. The raw
+*  token is the proof - holding it means the owner sent it to you. */
+function inviteInfo(dir, rawToken) {
+	const hash = sha256(rawToken);
+	const invite = loadStore(dir).invites.find((i) => i.tokenHash === hash && i.exp > Date.now());
+	return invite ? { email: invite.emailNorm } : null;
+}
+function createInvite(dir, email) {
+	return withLock(dir, () => {
+		const store = loadStore(dir);
+		if (findUser(store, email)) throw new Error(`${normEmail(email)} already has an account`);
+		const raw = token();
+		const exp = Date.now() + INVITE_TTL;
+		store.invites = store.invites.filter((i) => i.emailNorm !== normEmail(email));
+		store.invites.push({
+			emailNorm: normEmail(email),
+			tokenHash: sha256(raw),
+			exp
+		});
+		saveStore(dir, store);
+		return {
+			token: raw,
+			exp
+		};
+	});
+}
+/** Claim an invite: burns it, creates the account, opens the first session. */
+function claimInvite(dir, rawToken, profile, ceilings = {}) {
+	if (profile.password.length < 8) throw new Error("password must be at least 8 characters");
+	if (!profile.name.trim()) throw new Error("a display name is required");
+	return withLock(dir, () => {
+		const store = loadStore(dir);
+		const hash = sha256(rawToken);
+		const invite = store.invites.find((i) => i.tokenHash === hash && i.exp > Date.now());
+		if (!invite) throw new Error("this invite link is invalid, expired, or already used");
+		if (findUser(store, invite.emailNorm)) {
+			store.invites = store.invites.filter((i) => i !== invite);
+			saveStore(dir, store);
+			throw new Error("an account already exists for this address - sign in instead");
+		}
+		store.invites = store.invites.filter((i) => i !== invite);
+		const salt = randomBytes(16).toString("hex");
+		const user = {
+			email: invite.emailNorm,
+			name: profile.name.trim(),
+			avatar: profile.avatar,
+			role: store.users.length ? "member" : "owner",
+			salt,
+			hash: scryptSync(profile.password, Buffer.from(salt, "hex"), SCRYPT.keylen, SCRYPT).toString("hex"),
+			params: SCRYPT,
+			createdAt: Date.now()
+		};
+		store.users.push(user);
+		grantFromInviteRedemption(dir, invite.emailNorm, ceilings);
+		const session = pushSession(store, user);
+		saveStore(dir, store);
+		return {
+			user,
+			session
+		};
+	});
+}
+/** Password sign-in. One generic failure - never reveal whether the email exists. */
+function signIn(dir, email, password, ceilings) {
+	return withLock(dir, () => {
+		const store = loadStore(dir);
+		const found = findUser(store, email);
+		const user = found && found.auth !== "marver-id" && found.salt && found.hash ? found : null;
+		const salt = user ? Buffer.from(user.salt, "hex") : randomBytes(16);
+		const params = user?.params ?? SCRYPT;
+		const got = scryptSync(password, salt, params.keylen, params);
+		const want = user ? Buffer.from(user.hash, "hex") : randomBytes(SCRYPT.keylen);
+		if (!user || got.length !== want.length || !timingSafeEqual(got, want)) return null;
+		const share = shareState(dir);
+		if (share && user.role !== "owner") {
+			if (provisionVerdict(share, user.email, {
+				ceilings,
+				exactOnly: true
+			}) !== "granted") return null;
+		}
+		const session = pushSession(store, user);
+		saveStore(dir, store);
+		return {
+			user,
+			session
+		};
+	});
+}
+/**
+* Turn a verified Marver ID identity into a local session.
+*
+* The identity service has already proved who this person is; this function
+* decides whether they may in - and that decision is LOCAL, which is the whole
+* shape of L1a. The identity service knows nothing about who is allowed where.
+*
+* `allowed` is the owner's allowlist. An email that is not on it gets no account
+* and no session: being able to prove you are someone is not the same as being
+* invited. The first allowed account to arrive owns the canvas, matching the
+* invite flow's rule.
+*
+* No password is fabricated. A marver-id account carries no salt or hash at all,
+* so there is no second, weaker door into it.
+*/
+function provisionFromMarverId(dir, identity, opts = {}) {
+	const emailNorm = normEmail(identity.email);
+	if (!emailNorm) return null;
+	return withLock(dir, () => {
+		const store = loadStore(dir);
+		const qualified = `${identity.issuer}#${identity.subject}`;
+		const bound = store.users.find((u) => u.idSubject === qualified);
+		const existing = bound ?? findUser(store, emailNorm);
+		let vacated = null;
+		if (bound && normEmail(bound.email) !== emailNorm) {
+			const clash = findUser(store, emailNorm);
+			if (clash && clash !== bound) return null;
+			vacated = normEmail(bound.email);
+			bound.email = emailNorm;
+			store.sessions = store.sessions.filter((s) => s.emailNorm !== vacated);
+		}
+		const invite = store.invites.find((i) => i.emailNorm === emailNorm && i.exp > Date.now());
+		const ownerNorm = opts.ownerEmail ? normEmail(opts.ownerEmail) : "";
+		const reservedForOwner = !!ownerNorm && !store.users.length && ownerNorm !== emailNorm;
+		const isBootstrapOwner = !!ownerNorm && !store.users.length && ownerNorm === emailNorm;
+		if (reservedForOwner) return null;
+		const share = shareState(dir);
+		if (share) {
+			const verdict = provisionVerdict(share, emailNorm, {
+				ceilings: opts.ceilings,
+				aliases: vacated ? [vacated] : void 0
+			});
+			if (verdict === "blocked") return null;
+			if (!(verdict === "granted" || existing?.role === "owner" || !!invite || isBootstrapOwner)) return null;
+		} else if (!existing && !invite && !isBootstrapOwner) return null;
+		if (invite) store.invites = store.invites.filter((i) => i !== invite);
+		let user = existing;
+		if (user) {
+			if (!user.idSubject) user.idSubject = qualified;
+			else if (user.idSubject === identity.subject) user.idSubject = qualified;
+			else if (user.idSubject !== qualified) return null;
+		} else {
+			user = {
+				email: emailNorm,
+				name: identity.name || emailNorm.split("@")[0] || emailNorm,
+				role: store.users.length ? "member" : "owner",
+				auth: "marver-id",
+				idSubject: `${identity.issuer}#${identity.subject}`,
+				createdAt: Date.now()
+			};
+			store.users.push(user);
+		}
+		if (identity.name && (!user.name || user.name === emailNorm.split("@")[0])) user.name = identity.name;
+		if (invite) grantFromInviteRedemption(dir, emailNorm, opts.ceilings);
+		if (vacated) renamePrincipalGrants(dir, vacated, emailNorm);
+		const session = pushSession(store, user);
+		saveStore(dir, store);
+		return {
+			user,
+			session
+		};
+	});
+}
+/**
+* Attach a picture the identity service supplied.
+*
+* Separate from provisioning because the fetch happens after admission and
+* outside the lock, so by the time there are bytes the account already exists.
+*
+* `avatarSource` is what makes this safe to repeat: its presence means "this
+* picture came from the identity service", and only such a picture may be
+* replaced. An avatar with no source was chosen HERE, by the person, and the
+* identity service does not get to overwrite it - which is the same rule the
+* name follows.
+*
+* Replacing a rotated one is the point. Refusing to, as an earlier version did,
+* meant the stored source never caught up with the assertion, so every single
+* sign-in fetched the new picture and then threw it away.
+*/
+function attachAvatar(dir, subjectQualified, avatar, source, expected) {
+	withLock(dir, () => {
+		const store = loadStore(dir);
+		const user = store.users.find((u) => u.idSubject === subjectQualified);
+		if (!user) return;
+		if (user.avatar && !user.avatarSource) return;
+		if (user.avatarSource !== expected) return;
+		user.avatar = avatar;
+		user.avatarSource = source;
+		saveStore(dir, store);
+	});
+}
+/**
+* Would a picture from the identity service actually be used?
+*
+* Read-only and outside the lock, so the gate can decide whether a network
+* fetch is worth making before it commits to one. Worst case it is wrong and we
+* fetch a picture that then gets discarded - which costs one request, versus
+* fetching an avatar on every single sign-in forever.
+*/
+function avatarSourceFor(dir, subjectQualified, email, pictureUrl) {
+	const store = loadStore(dir);
+	const user = store.users.find((u) => u.idSubject === subjectQualified) ?? findUser(store, normEmail(email));
+	if (!user) return {
+		wanted: true,
+		source: void 0
+	};
+	if (!user.avatar) return {
+		wanted: true,
+		source: user.avatarSource
+	};
+	if (!user.avatarSource) return {
+		wanted: false,
+		source: void 0
+	};
+	return {
+		wanted: user.avatarSource !== pictureUrl,
+		source: user.avatarSource
+	};
+}
+function pushSession(store, user) {
+	const raw = token();
+	store.sessions.push({
+		tokenHash: sha256(raw),
+		emailNorm: normEmail(user.email),
+		exp: Date.now() + SESSION_TTL
+	});
+	return raw;
+}
+/**
+* The canvas secret - the HMAC key behind opaque author ids (01-sharing §7.5).
+*
+* Generated once onto the volume, 0600, cached per process. The id it derives
+* is stable within a canvas and meaningless across canvases; a bare hash of an
+* email is guessable (the address space is small), which is why this is keyed.
+*/
+const secretCache = /* @__PURE__ */ new Map();
+function canvasSecret(dir) {
+	const hit = secretCache.get(dir);
+	if (hit) return hit;
+	const file = join(dir, "canvas.secret");
+	const read = () => {
+		try {
+			const key = Buffer.from(readFileSync(file, "utf8").trim(), "hex");
+			return key.length === 32 ? key : null;
+		} catch {
+			return null;
+		}
+	};
+	const key = read() ?? withLock(dir, () => {
+		const again = read();
+		if (again) return again;
+		const fresh = randomBytes(32);
+		const tmp = `${file}.${randomBytes(6).toString("hex")}.tmp`;
+		const fd = openSync(tmp, "wx", 384);
+		try {
+			writeSync(fd, fresh.toString("hex"));
+			fsyncSync(fd);
+		} finally {
+			closeSync(fd);
+		}
+		renameSync(tmp, file);
+		return fresh;
+	});
+	secretCache.set(dir, key);
+	return key;
+}
+/** The opaque per-canvas author id: HMAC(canvas secret, lowercased email). */
+function opaqueId(dir, email) {
+	return createHmac("sha256", canvasSecret(dir)).update(normEmail(email)).digest("hex").slice(0, 24);
+}
+/** Was this session minted by the operator credential? The CLI sync path keeps
+*  the RAW author profile (the agent needs real addresses and the operator
+*  already owns the canvas); every other caller gets the projection. */
+function sessionIsOperator(dir, rawToken) {
+	const store = loadStore(dir);
+	const hash = sha256(rawToken);
+	const s = store.sessions.find((s) => s.tokenHash === hash && s.exp > Date.now());
+	return !!s?.via && s.via === operatorFingerprint();
+}
+function sessionUser(dir, rawToken) {
+	const store = loadStore(dir);
+	const hash = sha256(rawToken);
+	const s = store.sessions.find((s) => s.tokenHash === hash && s.exp > Date.now());
+	if (!s) return null;
+	if (s.via && s.via !== operatorFingerprint()) return null;
+	return store.users.find((u) => normEmail(u.email) === s.emailNorm) ?? null;
+}
+/** The alphabet a bearer token can actually travel in: both the gate and the API
+*  parse `Authorization` with `[\w-]+`, so a secret containing anything else is
+*  accepted at boot and then silently unusable. Checked HERE as well as at boot so
+*  the two can never drift apart. */
+const CLI_TOKEN_CHARS = /^[\w-]+$/;
+/**
+* The operator's own credential, read from the deployment environment.
+*
+* `comments connect` authenticates with a password, and an identity account has
+* none by design - so on an identity-gated canvas the whole CLI surface (invite,
+* revoke, and the comment sync the agent loop runs on) had no reachable
+* credential. This is the door, and where it lives is the entire point.
+*
+* The obvious alternative - a page that mints a token for whoever is signed in -
+* is the device flow this project already built and pulled (2d0850c). Authored
+* frames run same-origin in a canvas: frame JavaScript reads `mv_c`, every
+* request it makes carries the viewer's session, so any browser-reachable way to
+* mint a durable token is a way for a frame to mint one silently and carry it
+* off. There is no header that separates a frame from its own origin.
+*
+* An environment variable is on the other side of that line. It is never sent to
+* a page, no frame can read it, and reaching it already means reaching the
+* deployment - at which point the canvas was never the weakest thing in the room.
+* The cost is honest: it is a static secret that rotates by redeploying, and it
+* acts as the owner, so it is an operator credential rather than a person's.
+*/
+function operatorUser(dir, presented) {
+	return operatorMatch(presented) ? ownerOf(dir) : null;
+}
+/** The owner's account, or null on a canvas nobody has claimed yet. Chosen by
+*  stored ROLE, never by array order or by whatever MARVER_OWNER_EMAIL currently
+*  says - that variable only ever nominated a bootstrap account, and honouring it
+*  afterwards would let a changed environment repoint this at a different person. */
+const ownerOf = (dir) => loadStore(dir).users.find((u) => u.role === "owner") ?? null;
+/**
+* Why a configured `MARVER_CLI_TOKEN` is unusable, or null when it is fine.
+*
+* One function so that boot and the matcher can never disagree. They did: boot
+* trimmed the value before checking it while `comments connect` sent the shell's
+* value as-is, so `" abcd... "` started a canvas that then refused the operator's
+* own token with no explanation anywhere. Surrounding whitespace is now a refusal
+* rather than something quietly repaired on one side of the wire.
+*/
+function cliTokenProblem(raw) {
+	if (!raw) return null;
+	if (raw !== raw.trim()) return "MARVER_CLI_TOKEN has whitespace around it - quote it, or drop the quotes that put it there";
+	if (raw.length < 32) return `MARVER_CLI_TOKEN is too short to be a bearer credential (${raw.length} chars, needs 32)`;
+	if (!CLI_TOKEN_CHARS.test(raw)) return "MARVER_CLI_TOKEN contains characters that cannot travel in an Authorization header";
+	return null;
+}
+/** The configured secret, or '' when there is none worth honouring. Never trimmed
+*  into shape: a value that needed trimming was refused at boot. */
+const operatorSecret = () => {
+	const raw = process.env.MARVER_CLI_TOKEN ?? "";
+	return raw && !cliTokenProblem(raw) ? raw : "";
+};
+/** A fingerprint of the current secret, so a session can record WHICH one minted
+*  it. The hash, never the value: this is written to auth.json, and a store that
+*  quietly contains the operator's credential is the thing being avoided. */
+const operatorFingerprint = () => {
+	const secret = operatorSecret();
+	return secret ? sha256(`cli-generation:${secret}`) : "";
+};
+function operatorMatch(presented) {
+	const secret = operatorSecret();
+	if (!secret || !presented) return false;
+	return timingSafeEqual(Buffer.from(sha256(presented), "hex"), Buffer.from(sha256(secret), "hex"));
+}
+/**
+* Trade the operator's secret for an ordinary session, once, from the terminal.
+*
+* The secret itself must not become the thing a repo carries. `connect` persists
+* whatever it is given, and that file sits on a developer's disk for as long as
+* the project lasts - a non-expiring master key is the wrong shape for it. What comes back here expires, dies with
+* `comments revoke`, and can be replaced without touching the deployment.
+*
+* Only the operator secret opens this. Deliberately NOT any signed-in session:
+* authored frames run same-origin and ride the viewer's cookies, so a route that
+* minted sessions for whoever was signed in would be the pulled device flow
+* (2d0850c) with a different name. A frame cannot present this Bearer, because
+* the value it needs was never in the browser.
+*/
+function issueDeviceSession(dir, presented) {
+	if (!operatorMatch(presented)) return null;
+	return withLock(dir, () => {
+		const store = loadStore(dir);
+		const user = store.users.find((u) => u.role === "owner");
+		if (!user) return null;
+		const token = pushSession(store, user);
+		store.sessions[store.sessions.length - 1].via = operatorFingerprint();
+		saveStore(dir, store);
+		return {
+			token,
+			exp: Date.now() + SESSION_TTL,
+			user
+		};
+	});
+}
+function signOut(dir, rawToken) {
+	withLock(dir, () => {
+		const store = loadStore(dir);
+		const hash = sha256(rawToken);
+		store.sessions = store.sessions.filter((s) => s.tokenHash !== hash);
+		saveStore(dir, store);
+	});
+}
+/** Update name/avatar on an existing account. */
+function updateProfile(dir, email, patch) {
+	return withLock(dir, () => {
+		const store = loadStore(dir);
+		const user = findUser(store, email);
+		if (!user) throw new Error("no such account");
+		if (patch.name?.trim()) user.name = patch.name.trim();
+		if (patch.avatar !== void 0) {
+			user.avatar = patch.avatar || void 0;
+			user.avatarSource = void 0;
+		}
+		saveStore(dir, store);
+		return user;
+	});
+}
+/** Remove an account and all its sessions (owner action). The LAST owner cannot be
+*  removed - a store with members but no owner has no one left to administer it,
+*  and bootstrap will not re-run while any user exists. */
+function revokeUser(dir, email) {
+	withLock(dir, () => {
+		const store = loadStore(dir);
+		if (store.users.find((u) => normEmail(u.email) === normEmail(email))?.role === "owner" && !store.users.some((u) => u.role === "owner" && normEmail(u.email) !== normEmail(email))) throw new Error("cannot remove the last owner - the canvas would have no administrator left");
+		store.users = store.users.filter((u) => normEmail(u.email) !== normEmail(email));
+		store.sessions = store.sessions.filter((s) => s.emailNorm !== normEmail(email));
+		store.invites = store.invites.filter((i) => i.emailNorm !== normEmail(email));
+		saveStore(dir, store);
+	});
+	removePrincipalGrants(dir, email);
+}
+/** The public shape of a user - what other viewers (and events) may see. */
+const publicUser = (u) => ({
+	email: u.email,
+	name: u.name,
+	avatar: u.avatar
+});
+//#endregion
+export { reconfirmGrant as A, commentAllowed as C, operativeMode as D, loadShare as E, setBlocked as F, setGeneralMode as I, shareState as L, resolveAccess as M, resolveRequest as N, provisionVerdict as O, rosterEtag as P, share_exports as R, ceilingsFromRights as S, loadRequests as T, sessionUser as _, claimInvite as a, updateProfile as b, issueDeviceSession as c, opaqueId as d, ownerName as f, sessionIsOperator as g, revokeUser as h, avatarSourceFor as i, removeGrant as j, putRequest as k, loadStore as l, publicUser as m, attachAvatar as n, createInvite as o, provisionFromMarverId as p, auth_exports as r, inviteInfo as s, CLI_TOKEN_CHARS as t, normEmail as u, signIn as v, entryAllowed as w, withLock as x, signOut as y, upsertGrant as z };