visualproof 0.0.0-stage → 0.2.0

package/dist/server/identity.js

@@ -0,0 +1,114 @@
+// Who records something (CollabSpec decision 3). By default the name the page gives, as it gives
+// it: any name, changed at will, nothing checked (relaxed on 2026-10-07 — names used to be claimed
+// with a secret). The page sends it with every request as `X-VisualProof-Name`, percent-encoded so
+// that any script travels in a header. Behind a proxy that signs people in, the name is the one the
+// proxy puts in its own header instead, and the page cannot change it.
+//
+// Someone invited by a personal link (CollabSpec decision 9, server/invites.ts) is who the link's
+// cookie says, whatever the page sends: the link's id is who they are, and the name they go by is
+// the link's, changed through the server. While their link is in force, nobody coming by the key's
+// link (a guest) can go by that name: such a request is taken as one without a name, so that
+// whatever needs one is refused and the page asks for another (`taken` says why).
+//
+// An agent says it is one (AgentSpec decision 1) with `X-VisualProof-Kind: agent` beside its name.
+// Nothing checks that either: the kind is what makes its opinions advice, so an agent that does not
+// say it is one is taken for a person, as a person who says so is taken for an agent.
+//
+// A private reader (CollabSpec decision 8) says so with every request, `X-VisualProof-Private`
+// carrying what the page calls itself (its event stream's session). What they arrange is recorded
+// without their name (layoutAuthor, below); their review keeps it.
+import { validName, validSession } from "../shared/collab.js";
+export const NAME_HEADER = "x-visualproof-name";
+export const KIND_HEADER = "x-visualproof-kind";
+export const PRIVATE_HEADER = "x-visualproof-private";
+export class Identities {
+    /** the header an authenticating proxy names the reader in, or null: the page's name is taken */
+    header;
+    /** the personal links (server/invites.ts), which say who their holders are; none behind a proxy
+     *  that signs people in, whose names are the proxy's */
+    invites = null;
+    /** what each request's cookie said, read once per request */
+    seen = new WeakMap();
+    constructor(header = null) {
+        this.header = header ? header.toLowerCase() : null;
+    }
+    get mode() {
+        return this.header ? "header" : "declared";
+    }
+    /** What the personal link's cookie a request carries says: a link in force, one revoked, none. */
+    link(req) {
+        if (this.header || !this.invites)
+            return null;
+        if (!this.seen.has(req))
+            this.seen.set(req, this.invites.ofCookie(req.headers.cookie));
+        return this.seen.get(req);
+    }
+    /** The holder of a personal link in force a request comes from, or null. */
+    person(req) {
+        const l = this.link(req);
+        return l && "ok" in l ? l.ok : null;
+    }
+    /** The name a request is made under, or null when it gives none — or gives one a holder of a
+     *  personal link goes by, and is not theirs. */
+    who(req) {
+        const p = this.person(req);
+        if (p)
+            return p.name;
+        const s = this.said(req);
+        return s && !this.taken(req, s) ? s : null;
+    }
+    /** The holder of a personal link in force who goes by the name a guest's request gives, which is
+     *  then not theirs to take; null for any other request. An agent's names are its own: it is
+     *  marked as one wherever it is named. */
+    taken(req, name = this.said(req)) {
+        if (!name || !this.invites || this.header || this.person(req) || this.kind(req) === "agent")
+            return null;
+        return this.invites.holder(name) ?? null;
+    }
+    /** The name a request's headers give, checked to be a name. */
+    said(req) {
+        const raw = req.headers[this.header ?? NAME_HEADER];
+        let s = (Array.isArray(raw) ? raw[0] : raw)?.trim();
+        if (!s)
+            return null;
+        if (!this.header) {
+            try {
+                s = decodeURIComponent(s);
+            }
+            catch {
+                return null;
+            }
+        }
+        return validName(s) ? s : null;
+    }
+    /** Whether a request comes from an agent: it says so. A personal link's holder is a person. */
+    kind(req) {
+        if (this.person(req))
+            return "person";
+        const raw = req.headers[KIND_HEADER];
+        return (Array.isArray(raw) ? raw[0] : raw)?.trim().toLowerCase() === "agent" ? "agent" : "person";
+    }
+    /** Whether a request comes from a private page (CollabSpec decision 8): the session the page
+     *  calls itself by, "" where it gives none, or null for any other request. An agent is never
+     *  private, whatever it sends: its token or its name is who it is, and it is always listed. Nothing
+     *  checks a page that says it is private either: it only gives up its name on what it arranges. */
+    privateOf(req) {
+        if (this.kind(req) === "agent")
+            return null;
+        const raw = req.headers[PRIVATE_HEADER];
+        const s = (Array.isArray(raw) ? raw[0] : raw)?.trim();
+        if (s === undefined)
+            return null;
+        return validSession(s) ? s : "";
+    }
+}
+/** The name a change to the layout is recorded under (CollabSpec decision 8): the caller's, or none
+ *  for a private reader, who shows as "someone" — on the boards, in Activity, among pin authors and
+ *  in the agents' answers. This is where a private reader's anonymity lives: whatever arranges a
+ *  board — pins, folds, re-layouts, scopes and clusterings, views made, renamed and deleted, notes
+ *  left on a board — takes its author from here, through server/views.ts (`handle`, whose `me` is
+ *  this) and main.ts (an undo). The review is not layout: opinions, targets, key marks and trust
+ *  take the caller's own name, and need one. */
+export function layoutAuthor(caller) {
+    return caller.private ? null : caller.name;
+}

package/dist/server/invites.js

@@ -0,0 +1,241 @@
+// Personal links (CollabSpec decision 9, the owner's decision of 2026-10-09): someone on the server
+// invites a person by name from Share, and the server makes a link for that person alone. The link
+// lets its holder in, as the key's link does (server/access.ts), and says who they are: the
+// holder's identity is the link's id, and the name is only what they are called — they rename
+// themselves from the menu under it, and what they did stays theirs, shown under the new name.
+// Their review goes to one log named by the id (shared/review.ts, logFileName), so a rename never
+// starts a new file. Nobody else can take the name they go by while their link is in force.
+//
+// A link is `/i/vpp_<id>_<secret>`, the token made as an agent's is (server/tokens.ts): the prefix
+// makes one recognisable wherever it is pasted, the id names it in lists and in the review's logs
+// (it is no secret), the secret is 32 random bytes. Opened, it leaves a cookie in the browser and
+// goes on to the page, so that the token leaves the address; the cookie's value is made from the
+// token, never the token itself (cookies are not kept per port, and other services answer on this
+// host's name), and its name is this server's own, so two servers on one host keep theirs apart.
+//
+// A link lasts until it is revoked. An agent's token lasts days, since it hands a program a
+// credential for a piece of work; a person's link is who they are in the review, and its id names
+// their log: if it ran out, the same person would come back with a new link as someone else, with a
+// log of their own. The key's link never runs out either, and a personal link reaches no further.
+// Share lists every link in force with when it was last used, so that one nobody uses any more is
+// seen and revoked, which cuts it off at once — its pages' event streams too.
+//
+// The token is shown once, to whoever made it, for them to send: the server keeps only its digest,
+// in `<site>/person-invites.json` (readable by its owner alone, as the access key and the agents'
+// tokens are). Showing it again would let anyone on the server be that person. Revoked links are
+// kept, with every name their holders went by, so that what they did keeps its name; they never let
+// anyone in again. When a link was last used is written at most once a minute, as an agent token's.
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { MAX_NAME, sameName, validName } from "../shared/collab.js";
+import { validPersonId } from "../shared/review.js";
+export const INVITE_PREFIX = "vpp_";
+/** where a personal link points: `/i/<token>` */
+export const INVITE_PATH = "/i/";
+const FILE = "person-invites.json";
+/** what the cookie's name starts with; the rest is this server's own (`cookie` in its file) */
+const COOKIE = "visualproof_person";
+/** how long a browser stays let in: the longest browsers keep a cookie (400 days), renewed at each
+ *  visit to the page */
+const MAX_AGE = 400 * 24 * 3600;
+const FLUSH_MS = 60_000;
+const SECRET = /^[A-Za-z0-9_-]{43}$/;
+const sha = (s) => createHash("sha256").update(s).digest();
+const digestOf = (token) => sha(`visualproof person link\0${token}`).toString("base64url");
+/** the cookie's value for a link: its id, and a digest of what is kept of its token */
+const cookieValue = (r) => `${r.id}.${sha(`visualproof person cookie\0${r.digest}`).toString("base64url")}`;
+/** Whether `a` and `b` are the same, in constant time whatever they are. */
+function same(a, b) {
+    return timingSafeEqual(sha(a), sha(b));
+}
+export class Invites {
+    file;
+    records = [];
+    /** the cookie's name: `visualproof_person_` and this server's own 12 hex digits */
+    cookieName;
+    dirty = false;
+    timer = null;
+    /** told when a link is revoked: its pages' event streams end (server/live.ts) */
+    onEnded = () => { };
+    /** told when a link was made, renamed or revoked: every page is told the names (`people`) */
+    onChanged = () => { };
+    /** `siteDir` null keeps the links in memory only (tests). */
+    constructor(siteDir) {
+        this.file = siteDir ? join(siteDir, FILE) : null;
+        let own = null;
+        if (this.file && existsSync(this.file)) {
+            try {
+                const data = JSON.parse(readFileSync(this.file, "utf8"));
+                if (typeof data.cookie === "string" && /^[0-9a-f]{12}$/.test(data.cookie))
+                    own = data.cookie;
+                if (Array.isArray(data.invites))
+                    this.records = data.invites.filter(isRecord);
+            }
+            catch {
+                // a file that cannot be read lets nobody in by a link; it is kept aside, not overwritten
+                renameSync(this.file, `${this.file}.broken-${Date.now()}`);
+            }
+        }
+        // the cookie's name is kept with the first link: before there is one, no browser has the cookie
+        this.cookieName = `${COOKIE}_${own ?? randomBytes(6).toString("hex")}`;
+        if (!own && this.records.length)
+            this.save();
+        if (this.file) {
+            this.timer = setInterval(() => this.flush(), FLUSH_MS);
+            this.timer.unref?.();
+        }
+    }
+    /** Make a link for a person, under the name `name` (checked by the caller), made by `by`: the
+     *  token, for the link, and its record; or why not — a name someone with a link in force goes by
+     *  is theirs. */
+    create(o) {
+        const now = new Date(o.now ?? Date.now()).toISOString();
+        const name = o.name.trim();
+        const holder = this.holder(name);
+        if (holder)
+            return taken(holder);
+        let id;
+        do
+            id = randomBytes(5).toString("hex");
+        while (this.records.some((r) => r.id === id));
+        const token = `${INVITE_PREFIX}${id}_${randomBytes(32).toString("base64url")}`;
+        const record = { id, digest: digestOf(token), name, names: [{ name, at: now }], by: o.by, created: now, revoked: null, revokedBy: null, lastUsed: null };
+        this.records.push(record);
+        this.save();
+        this.onChanged();
+        return { token, record };
+    }
+    /** What a link's token is. Compared in constant time, by digests of one length whatever was sent,
+     *  whether or not its id is known. */
+    check(token, now = Date.now()) {
+        if (!token.startsWith(INVITE_PREFIX))
+            return null;
+        const id = token.slice(INVITE_PREFIX.length, INVITE_PREFIX.length + 10);
+        const r = validPersonId(id) && token[INVITE_PREFIX.length + 10] === "_" && SECRET.test(token.slice(INVITE_PREFIX.length + 11)) ? this.get(id) : undefined;
+        const ok = same(digestOf(token), r?.digest ?? "no such link");
+        return r && ok ? this.seen(r, now) : null;
+    }
+    /** What the cookie a request carries says (its `Cookie` header): a link in force, one revoked
+     *  (whose cookie the browser should forget), or none. */
+    ofCookie(header, now = Date.now()) {
+        const given = cookieOf(header, this.cookieName);
+        if (given === null)
+            return null;
+        const r = given.indexOf(".") === 10 ? this.get(given.slice(0, 10)) : undefined;
+        const ok = same(given, r ? cookieValue(r) : "no such link");
+        return r && ok ? this.seen(r, now) : null;
+    }
+    seen(r, now) {
+        if (r.revoked)
+            return { ended: "revoked", record: r };
+        r.lastUsed = new Date(now).toISOString();
+        this.dirty = true;
+        return { ok: r };
+    }
+    /** The cookie that lets a browser in as the holder of `r` (a `Set-Cookie` value). */
+    cookie(r) {
+        return `${this.cookieName}=${cookieValue(r)}; Path=/; Max-Age=${MAX_AGE}; HttpOnly; SameSite=Lax`;
+    }
+    /** What makes a browser forget a revoked link's cookie. */
+    forget() {
+        return `${this.cookieName}=; Path=/; Max-Age=0; HttpOnly; SameSite=Lax`;
+    }
+    /** The links in force, oldest first. */
+    inForce() {
+        return this.records.filter((r) => !r.revoked);
+    }
+    get(id) {
+        return this.records.find((r) => r.id === id);
+    }
+    /** The holder of a link in force who goes by `name` (sameName), but `except`; undefined when
+     *  nobody does. */
+    holder(name, except = null) {
+        return this.inForce().find((r) => r.id !== except && sameName(r.name, name));
+    }
+    /** The holder of a link in force goes by `name` from now on (checked by the caller); every name
+     *  they had is kept. The record, or why not: the name is another holder's. */
+    rename(id, name, now = Date.now()) {
+        const r = this.get(id);
+        if (!r || r.revoked)
+            return "This personal link was revoked.";
+        const n = name.trim();
+        const other = this.holder(n, id);
+        if (other)
+            return taken(other);
+        if (r.name === n)
+            return r;
+        r.name = n;
+        r.names.push({ name: n, at: new Date(now).toISOString() });
+        this.save();
+        this.onChanged();
+        return r;
+    }
+    /** Revoke a link in force: it lets nobody in from now on, and its pages' event streams end.
+     *  False when there is no such link in force. */
+    revoke(id, by, now = Date.now()) {
+        const r = this.get(id);
+        if (!r || r.revoked)
+            return false;
+        r.revoked = new Date(now).toISOString();
+        r.revokedBy = by;
+        this.save();
+        this.onEnded(r);
+        this.onChanged();
+        return true;
+    }
+    /** Every holder of a link, revoked ones too, as every page is told them (`Invited`). */
+    people() {
+        return this.records.map((r) => ({ id: r.id, name: r.name, was: [...new Set(r.names.map((n) => n.name).filter((n) => n !== r.name))], ...(r.revoked ? { revoked: true } : {}) }));
+    }
+    /** Write when links were last used, if that changed since the last write. */
+    flush() {
+        if (this.dirty)
+            this.save();
+    }
+    /** Stop writing on a timer (tests, the server's end), writing what is left. */
+    close() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+        this.flush();
+    }
+    /** A link as Share shows it: no digest. */
+    static info(r) {
+        const { digest: _, ...rest } = r;
+        return { ...rest, names: rest.names.map((n) => ({ ...n })) };
+    }
+    save() {
+        this.dirty = false;
+        if (!this.file)
+            return;
+        const tmp = `${this.file}.tmp`;
+        writeFileSync(tmp, JSON.stringify({ cookie: this.cookieName.slice(COOKIE.length + 1), invites: this.records }, null, 1) + "\n", { mode: 0o600 });
+        renameSync(tmp, this.file);
+    }
+}
+/** Why a name is not to be had: someone with a personal link goes by it. */
+export function taken(r) {
+    return `“${r.name}” is the name of someone invited with a personal link: choose another.`;
+}
+/** Why a name a person is to be invited under, or to take, will not do; null when it will. */
+export function invalidPersonName(s) {
+    if (typeof s !== "string" || !validName(s.trim()))
+        return `A name is 1 to ${MAX_NAME} characters, without line breaks.`;
+    return null;
+}
+/** A cookie's value as the `Cookie` header carries it, or null. */
+export function cookieOf(header, name) {
+    for (const part of (header ?? "").split(";")) {
+        const eq = part.indexOf("=");
+        if (eq > 0 && part.slice(0, eq).trim() === name)
+            return part.slice(eq + 1).trim();
+    }
+    return null;
+}
+/** A record as this server keeps it; anything else is dropped when the file is read. */
+function isRecord(x) {
+    const r = x;
+    return (!!r && typeof r === "object" && validPersonId(r.id) && typeof r.digest === "string" && typeof r.name === "string" && validName(r.name) &&
+        Array.isArray(r.names) && r.names.every((n) => n && typeof n.name === "string" && typeof n.at === "string") && typeof r.by === "string" && typeof r.created === "string");
+}

package/dist/server/layoutthread.js

@@ -0,0 +1,51 @@
+// The graph's layouts, off the server's thread: computeLayout then stabilize, for each clustering in
+// a worker of its own, both at once. Laid out on the server's thread, Sphere-Packing-Lean's graph held
+// every request for seconds (2.5 s a clustering, more against a memory far off); a worker holds
+// none. A worker is given what a layout reads of each declaration, the edges and the memory, as
+// the page's own (web/src/layoutworker.ts), and gives the layout back. This module is its own
+// worker, so that a checkout (TypeScript) and the package (JavaScript) find it alike.
+import { Worker, isMainThread, parentPort, workerData } from "node:worker_threads";
+import { computeLayout, stabilize } from "../shared/layout.js";
+/** A clustering's layout, here: computeLayout, then stabilize against the memory. */
+export function layOutHere(mode, nodes, edges, memory) {
+    const all = nodes;
+    return stabilize(computeLayout(mode, all, edges), all, memory);
+}
+/** A clustering's layout, in a worker. Should no worker start, or one fail, it is laid out here:
+ *  slower to answer others meanwhile, never wrong. */
+export function layOutOffThread(mode, nodes, edges, memory) {
+    const ask = { vpLayout: true, mode, nodes: nodes.map(({ name, module, ext }) => (ext ? { name, module, ext } : { name, module })), edges, memory };
+    return new Promise((ok) => {
+        let done = false;
+        const here = () => {
+            if (done)
+                return;
+            done = true;
+            ok(layOutHere(mode, nodes, edges, memory));
+        };
+        let worker;
+        try {
+            worker = new Worker(new URL(import.meta.url), { workerData: ask });
+        }
+        catch {
+            return here();
+        }
+        worker.once("message", (layout) => {
+            if (done)
+                return;
+            done = true;
+            ok(layout);
+            void worker.terminate();
+        });
+        worker.once("error", here);
+        worker.once("exit", (code) => {
+            if (code !== 0)
+                here();
+        });
+    });
+}
+// in a worker: the one layout asked, and back
+if (!isMainThread && workerData?.vpLayout) {
+    const a = workerData;
+    parentPort.postMessage(layOutHere(a.mode, a.nodes, a.edges, a.memory));
+}