tosijs-ui 1.8.0 → 1.9.0-beta.2

package/CHANGELOG.md

@@ -1,5 +1,87 @@
 # Changelog
 
+## 1.9.0-beta.2
+
+> Prerelease — install with `tosijs-ui@beta`. `latest` stays on 1.8.0.
+
+**Remote editing, authenticated.** `bun run tunnel` exposes this machine's dev server at
+a public URL; a single-use invite link is exchanged for a durable session cookie, and
+editing through it is indistinguishable from sitting at the keyboard — same dev server,
+same watcher, same files.
+
+- **`bun run tunnel`** (`--status` / `--close` / `--link`). An SSH reverse tunnel to your
+  preview box. **The box does no compute** — it terminates TLS and checks a credential —
+  which is what lets one small VPS serve many projects. The work stays where the data is.
+- **Magic-link auth.** Two tokens on purpose: the **link** rides in a URL so it is the
+  one that leaks (history, `Referer`, proxy logs, chat-app link previews) and is
+  therefore *single-use and 15 minutes*; the **session** never appears in a URL, arrives
+  as an `HttpOnly` cookie, and is durable. A durable token pasted into a URL would be
+  strictly worse than basic auth. `SameSite=Lax` gives the write endpoint free CSRF
+  protection.
+- **`tunnel.requireToken`** — default `false`: the workspace renders for anyone with the
+  URL but **writes always need a session**, so a stranger gets a read-only page. Set
+  `true` to require a session even to view. The default means an expired link degrades
+  to a readable page rather than a wall — which is what you hit when you already hold a
+  session and open a second window.
+- **Security fix: source endpoints are no longer exposed to your LAN.** `Bun.serve` binds
+  every interface, so on any shared network an unauthenticated `POST /__docstore/source`
+  was **remote code execution** — write a repo file, the watcher rebuilds, the build runs
+  it. Now: loopback, or a valid session.
+- **Multi-project preview host.** Projects **self-register** — each deploy writes its own
+  Caddy fragment, so adding one touches no shared config and needs no DNS change. The
+  deploy validates before reloading and refuses on invalid config, so one bad fragment
+  can't break routing for everyone. The root serves a **generated index** of what's
+  deployed and which commit each is serving.
+- **Invite links replace basic-auth dialogs** on the static preview hosts too. Knowingly
+  weaker than the workspace's auth (a shared bearer secret in a cookie, not a per-client
+  session) — Caddy serving static files has no session store — but equivalent to the
+  basicauth it replaces, with no dialog.
+
+
+## 1.9.0-beta.1
+
+> **Prerelease.** The preview-host system works end to end and is in daily use, but the
+> plan it belongs to (`REMOTE-ACCESS-PLAN.md`) has two more phases. Published under the
+> `beta` dist-tag — **install with `tosijs-ui@beta`**; `latest` stays on 1.8.0.
+>
+> It's a **minor**, not a patch, despite being unfinished: it adds public API
+> (`SiteConfig.preview`), emits a new artifact into every adopter's output
+> (`/version.json`), and changes what happens when a build fails. Semver tracks the
+> shape of a change, not how done it feels.
+
+- **New: preview hosting.** `bun run deploy` rsyncs the built site to a box you control,
+  so a phone, a client, or a reviewer can see it without your dev server — or your
+  laptop — being up. The whole artifact is a few MB, so this is a copy, not a pipeline.
+  - **`preview: { host, path?, url? }`** in the site config. Only `host` is required;
+    `path` defaults to `/srv/preview/<name>`. Flag > env > config, so a one-off push
+    elsewhere doesn't need a config edit.
+  - **Dry run by default.** It runs `rsync --delete` (the remote must mirror the build,
+    stale pages must not linger), so the destructive form has to be typed: `--go`. It
+    also refuses any target that isn't an absolute path at least two levels deep.
+  - **Projects self-register.** Each deploy writes its own Caddy fragment; the server
+    glob-imports them. Adding a project touches no shared config and needs no DNS
+    change. The deploy **validates before reloading** and refuses to reload on invalid
+    config, so one bad fragment can't take down every project on the box.
+  - `deploy/Caddyfile` and `deploy/build-index.sh` are committed — server config in git
+    beats server config in someone's shell history.
+- **New: `/version.json`** in every build — `{ generator, site, commit, commitTime }`.
+  Nothing exposed which commit produced a given site before. It matters wherever a
+  deploy is a snapshot: a reviewer can otherwise report a bug you fixed this morning
+  with no way to tell from the page which of you is stale.
+  **Deliberately deterministic** — no build timestamp, no dirty flag — so a committed
+  output dir doesn't churn on every build. Git fields are omitted (never blank) when
+  git isn't available.
+- **Fix: a failed rebuild no longer destroys the site.** `buildSite()` opens with
+  `rm -rf <outputDir>`, so a build failing after that left nothing to serve — save a
+  typo, and the next refresh was a dead site. The dev server now moves the working
+  build aside first and restores it on failure, **and says so on the page**: the
+  existing floating widget (which already means "the far end has something to tell
+  you") shows the failure until a good build clears it, with detail in the console.
+  Note it survives the "tests disabled" preference — otherwise the one person who
+  turned test indicators off is the one who never learns their build is broken.
+- **New: `DEV_NO_WATCH=1`** serves the built site without watching, for automated
+  suites that want a server rather than a rebuilder.
+
 ## 1.8.0
 
 > **Read this first if you use `tosijs-ui/site`.** This release adds a **dependency-audit
@@ -47,6 +129,16 @@
   filename with a raw NUL byte, which makes macOS `grep` silently match **nothing** in that
   file (exit 1, no message) — so searching it for any symbol came back empty and the sort bug
   above was effectively unfindable. The comparator needs no delimiter; the NUL is gone.
+  - **Adopting the gate — budget for one upgrade, not one pin.** From the first real
+    adoption (`tosijs`, which went from 12 blocking advisories to zero): if the gate flags
+    **`brace-expansion`**, note that `GHSA-mh99-v99m-4gvg` marks *every* version below
+    **5.0.8** affected, so the override is mandatory — and `brace-expansion@5` breaks
+    **eslint 8**'s bundled `minimatch@3` with `expand is not a function`. In practice that
+    means **an eslint 8 → 10 migration** (flat config + typescript-eslint 8), not a one-line
+    pin. The upside is that it clears the whole `minimatch`/`js-yaml`/`flatted` cluster at
+    once — which is exactly what the advisories-per-package tally is telling you when it
+    fingers a stale toolchain. Expect "replace, don't patch" to be the right answer more
+    often than a targeted override.
 - **New: `openBrowser`** site-config option — opens the doc site on dev-server start, reusing
   an existing tab on macOS rather than piling up new ones.
 - **New: `DEV_NO_WATCH=1`** serves the built site without watching. The E2E lane used to run

package/README.md

@@ -16,14 +16,14 @@
 
 Copyright ©2023-2025 Tonio Loewald
 
-## ⚠️ Breaking change in 1.7.0 — `<tosi-code>` (ACE → CodeMirror 6)
-
-**1.7.0 is a breaking release shipping under a minor version, deliberately.** `<tosi-code>`
-moved from ACE to CodeMirror 6. `value`, `mode`, the `change` event, `disabled`, and
-`undo`/`redo` are unchanged; the ACE-era **`theme`** and **`options`** props are **removed** with
-no shim. Dark mode is now automatic (`body.darkmode`) and styling comes from `--code-bg` /
-`--text-color`. The `2.0` name is reserved for the tjs-native tosijs port, so this ships as
-1.7.0 — **pin `tosijs-ui@1.6` to defer.** Full detail and rationale in
+> ## ⚠️ Breaking change in 1.7.0 — `<tosi-code>` (ACE → CodeMirror 6)
+>
+> **1.7.0 is a breaking release shipping under a minor version, deliberately.** `<tosi-code>`
+> moved from ACE to CodeMirror 6. `value`, `mode`, the `change` event, `disabled`, and
+> `undo`/`redo` are unchanged; the ACE-era **`theme`** and **`options`** props are **removed** with
+> no shim. Dark mode is now automatic (`body.darkmode`) and styling comes from `--code-bg` /
+> `--text-color`. The `2.0` name is reserved for the tjs-native tosijs port, so this ships as
+> 1.7.0 — **pin `tosijs-ui@1.6` to defer.** Full detail and rationale in
 [CHANGELOG.md](./CHANGELOG.md).
 
 ## the tosijs-ui library

package/dist/doc-browser.js

@@ -191,6 +191,10 @@ const testIndicatorStyleSpec = {
     'body:not(.tests-enabled) .doc-link::after, body:not(.tests-enabled) .test-widget': {
         display: 'none !important',
     },
+    // ...EXCEPT a far-end status (a failed build). That is not a test result, so the
+    // "show test indicators" preference must not suppress it — otherwise the one
+    // person who turned tests off is the one who never learns their build is broken.
+    'body .test-widget.-dev-status': { display: 'flex !important' },
     // Nav link dot indicators
     '.doc-link.-test-passed::after, .doc-link.-test-failed::after': {
         content: "''",
@@ -1210,8 +1214,48 @@ export function createDocBrowser(options) {
         onClick: showTestMenu,
     }, span({ part: 'label' }, 'Tests'), span({ class: 'count', part: 'count' }, '0'));
     container.appendChild(testWidget);
+    /*
+    The far end has something to tell you.
+  
+    The dev server injects `window.__tosiDevStatus` at serve time when a rebuild has
+    FAILED — see statusSnippet() in site/dev-server.ts. That is the same kind of news
+    as a failing browser test (something broke; here is what), so it uses the same
+    floating widget rather than a second overlay competing for the same corner.
+  
+    Two differences from a test run, both deliberate:
+      - it does NOT auto-fade. A passing test run is over; a broken build is a standing
+        condition you have to act on, and it stays until a good build clears it.
+      - it wins ties. If tests also failed, the build failure is the more useful thing
+        to read first — the tests probably failed BECAUSE the build did.
+  
+    Nothing is injected when the server is healthy, so this is inert in production and
+    in a normal session.
+    */
+    const devStatus = globalThis.__tosiDevStatus;
+    let devStatusShown = false;
+    if (devStatus && devStatus.ok === false) {
+        devStatusShown = true;
+        const labelEl = testWidget.querySelector('[part="label"]');
+        const countEl = testWidget.querySelector('[part="count"]');
+        if (labelEl)
+            labelEl.textContent = devStatus.label || 'Build failed';
+        if (countEl)
+            countEl.hidden = true;
+        testWidget.classList.add('-failed', '-dev-status');
+        testWidget.hidden = false;
+        testWidget.title = devStatus.detail || '';
+        // The page you are reading is the LAST GOOD build — the dev server keeps serving
+        // it rather than the wreckage of the failed one — so say so plainly in the
+        // console, where the detail is readable and copyable.
+        console.error(`[tosi] ${devStatus.label || 'Build failed'} — showing the last good build.\n` +
+            (devStatus.detail || ''));
+    }
     let testsRunning = false;
     function setTestWidgetRunning() {
+        // A broken build outranks a test run: the tests very likely failed BECAUSE the
+        // build did, so replacing "Build failed" with "Tests" would hide the cause.
+        if (devStatusShown)
+            return;
         testsRunning = true;
         testWidget.hidden = false;
         testWidget.classList.remove('-passed', '-failed');

package/dist/doc-system/site/build-stamp.d.ts

@@ -0,0 +1,23 @@
+export interface BuildStamp {
+    /** the tosijs-ui version that generated this site */
+    generator: string;
+    /** the project's name, from site config */
+    site?: string;
+    /** short commit hash the site was built from, when available */
+    commit?: string;
+    /** ISO-8601 commit timestamp, when available */
+    commitTime?: string;
+}
+/** Injectable git seam for tests. Returns '' when the command can't run. */
+export type GitReader = (args: string[]) => Promise<string>;
+/**
+ * Collect build identity. Git fields are omitted (not blank) when unavailable, so
+ * `version.json` never asserts something it doesn't know.
+ */
+export declare function gatherBuildStamp(opts?: {
+    generator: string;
+    site?: string;
+    git?: GitReader;
+}): Promise<BuildStamp>;
+/** Serialize for `/version.json` (trailing newline so the file is diff-friendly). */
+export declare function serializeBuildStamp(stamp: BuildStamp): string;

package/dist/doc-system/site/build-stamp.js

@@ -0,0 +1,65 @@
+/*
+Build identity for a generated site: `/version.json`.
+
+Answers one question — **what am I looking at?** — for any deployed copy of the site.
+Nothing in the build exposed this before: `src/version.ts` is the *library* version,
+which says nothing about which commit of the CONSUMER's project produced a given
+build.
+
+That question is easy to shrug at locally and genuinely expensive elsewhere. A static
+deploy is a snapshot, so a preview host serves whatever was last pushed to it; someone
+reviews it, reports a bug you fixed this morning, and there is no way to tell from the
+page which of you is out of date. Same for a published doc site after a partial deploy.
+
+DELIBERATELY DETERMINISTIC — no build timestamp.
+
+`docs/` is committed in this repo (and in the other tosijs-* projects), so anything
+that changes on every build shows up as a diff on every commit. A wall-clock stamp
+would churn the tree forever and train everyone to ignore it — the same nuisance the
+non-reproducible ePub already causes. Identity comes from the COMMIT instead, so
+rebuilding the same source twice produces byte-identical output. That is also the more
+useful answer: you want to know which source this is, not when someone happened to run
+a build.
+
+There is no `dirty` flag for the same reason. A build made from a dirty tree reports
+its last commit, which may not describe what was actually built — so the warning
+belongs at DEPLOY time, where a human can act on it, not baked into a committed file
+that would then be permanently wrong.
+
+Best-effort by construction: a consumer of `tosijs-ui/site` may not be in a git repo
+at all, and a build must never fail because it couldn't read git metadata.
+*/
+import { $ } from 'bun';
+const defaultGit = async (args) => {
+    try {
+        const r = await $ `git ${args}`.nothrow().quiet();
+        return r.exitCode === 0 ? r.stdout.toString().trim() : '';
+    }
+    catch {
+        return ''; // git absent, not a repo, whatever — never fatal
+    }
+};
+/**
+ * Collect build identity. Git fields are omitted (not blank) when unavailable, so
+ * `version.json` never asserts something it doesn't know.
+ */
+export async function gatherBuildStamp(opts = {
+    generator: 'unknown',
+}) {
+    const git = opts.git ?? defaultGit;
+    const stamp = { generator: opts.generator };
+    if (opts.site)
+        stamp.site = opts.site;
+    const commit = await git(['rev-parse', '--short', 'HEAD']);
+    if (commit)
+        stamp.commit = commit;
+    // %cI is the committer date, strict ISO-8601 — stable for a given commit.
+    const commitTime = await git(['log', '-1', '--format=%cI']);
+    if (commitTime)
+        stamp.commitTime = commitTime;
+    return stamp;
+}
+/** Serialize for `/version.json` (trailing newline so the file is diff-friendly). */
+export function serializeBuildStamp(stamp) {
+    return JSON.stringify(stamp, null, 2) + '\n';
+}

package/dist/doc-system/site/dev-auth.d.ts

@@ -0,0 +1,41 @@
+/** A URL token is spent on first use, but must also age out if never used. */
+export declare const LINK_TOKEN_TTL_MS: number;
+/** Sessions are the durable half — long enough that you are not re-linking daily. */
+export declare const SESSION_TTL_MS: number;
+export declare const SESSION_COOKIE = "tosi_dev_session";
+/** 128 bits, base64url — long enough that guessing is not a threat model. */
+export declare function mintToken(): string;
+/** Constant-time compare that tolerates unequal lengths without throwing. */
+export declare function safeEqual(a: string, b: string): boolean;
+export interface AuthState {
+    /** unspent link tokens → when they expire */
+    links: Map<string, number>;
+    /** live session tokens → when they expire */
+    sessions: Map<string, number>;
+}
+export declare function createAuthState(): AuthState;
+/** Drop anything expired. Called on every use so the maps cannot grow without bound. */
+export declare function prune(state: AuthState, now: number): void;
+/** Issue a link token to put in a URL. */
+export declare function issueLink(state: AuthState, now: number): string;
+/**
+ * Spend a link token for a session token, or return null.
+ *
+ * Deleting BEFORE returning is what makes it single-use — and the delete happens
+ * whether or not the token had expired, so a replay of an expired token cannot linger.
+ */
+export declare function redeemLink(state: AuthState, token: string, now: number): string | null;
+/** Is this session token live? */
+export declare function validSession(state: AuthState, token: string | undefined | null, now: number): boolean;
+/** Pull one cookie out of a Cookie header. */
+export declare function readCookie(header: string | null | undefined, name: string): string | undefined;
+/** The Set-Cookie value for a freshly minted session. See the header comment. */
+export declare function sessionCookie(token: string, maxAgeMs?: number): string;
+/**
+ * Strip the link token from a URL so the redirect target is clean.
+ *
+ * The point of the exchange is that the token stops existing in the address bar, in
+ * history, and in anything the browser sends onward. Leaving it on the redirect would
+ * defeat the entire design.
+ */
+export declare function urlWithoutToken(rawUrl: string, param: string): string;

package/dist/doc-system/site/dev-auth.js

@@ -0,0 +1,134 @@
+/*
+Magic-link auth for the dev server, so a workspace exposed through `bun run tunnel`
+can be edited from anywhere.
+
+TWO TOKENS, ON PURPOSE.
+
+  LINK token   — travels in a URL (`https://…/?t=…`). Therefore it is the one that
+                 LEAKS: browser history, Referer headers, reverse-proxy access logs,
+                 link previews in chat apps that fetch what you paste, and anyone
+                 reading over your shoulder. So it is SINGLE-USE and short-lived: the
+                 first request spends it, and a copy scraped out of a log later is
+                 worthless.
+
+  SESSION token — never appears in a URL. Set as an HttpOnly cookie by the exchange
+                 and sent automatically thereafter, so it can be durable without being
+                 exposed. This is the one that actually authorises writes.
+
+That asymmetry is the whole design. A single durable token pasted into a URL would be
+strictly WORSE than basic auth: it would sit in five different logs forever. Exchanging
+it immediately for a cookie, then redirecting to a clean URL, is what makes "just send
+me a link" both convenient and defensible.
+
+Cookie flags, and why each:
+  HttpOnly          — script cannot read it, so an XSS in a rendered doc cannot exfil it
+  Secure            — never sent over plaintext
+  SameSite=Lax      — sent on top-level GET navigation (so clicking your link works),
+                      NOT on cross-site POST. That last part is free CSRF protection for
+                      the write endpoint: another origin cannot make your browser POST
+                      to /__docstore/source with your cookie attached.
+  Path=/            — the whole workspace, since editing spans the site
+
+Build-time only. Never import this from browser code.
+*/
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+/** A URL token is spent on first use, but must also age out if never used. */
+export const LINK_TOKEN_TTL_MS = 15 * 60 * 1000;
+/** Sessions are the durable half — long enough that you are not re-linking daily. */
+export const SESSION_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+export const SESSION_COOKIE = 'tosi_dev_session';
+/** 128 bits, base64url — long enough that guessing is not a threat model. */
+export function mintToken() {
+    return randomBytes(16).toString('base64url');
+}
+/** Constant-time compare that tolerates unequal lengths without throwing. */
+export function safeEqual(a, b) {
+    const ab = Buffer.from(a);
+    const bb = Buffer.from(b);
+    if (ab.length !== bb.length)
+        return false;
+    return timingSafeEqual(ab, bb);
+}
+export function createAuthState() {
+    return { links: new Map(), sessions: new Map() };
+}
+/** Drop anything expired. Called on every use so the maps cannot grow without bound. */
+export function prune(state, now) {
+    for (const [t, exp] of state.links)
+        if (exp <= now)
+            state.links.delete(t);
+    for (const [t, exp] of state.sessions)
+        if (exp <= now)
+            state.sessions.delete(t);
+}
+/** Issue a link token to put in a URL. */
+export function issueLink(state, now) {
+    prune(state, now);
+    const token = mintToken();
+    state.links.set(token, now + LINK_TOKEN_TTL_MS);
+    return token;
+}
+/**
+ * Spend a link token for a session token, or return null.
+ *
+ * Deleting BEFORE returning is what makes it single-use — and the delete happens
+ * whether or not the token had expired, so a replay of an expired token cannot linger.
+ */
+export function redeemLink(state, token, now) {
+    prune(state, now);
+    // Constant-time lookup over the (tiny) set rather than Map.get, so a timing signal
+    // can't distinguish "no such token" from "wrong token".
+    let matched = null;
+    for (const candidate of state.links.keys()) {
+        if (safeEqual(candidate, token))
+            matched = candidate;
+    }
+    if (matched === null)
+        return null;
+    state.links.delete(matched);
+    const session = mintToken();
+    state.sessions.set(session, now + SESSION_TTL_MS);
+    return session;
+}
+/** Is this session token live? */
+export function validSession(state, token, now) {
+    if (!token)
+        return false;
+    prune(state, now);
+    for (const candidate of state.sessions.keys()) {
+        if (safeEqual(candidate, token))
+            return true;
+    }
+    return false;
+}
+/** Pull one cookie out of a Cookie header. */
+export function readCookie(header, name) {
+    if (!header)
+        return undefined;
+    for (const part of header.split(';')) {
+        const eq = part.indexOf('=');
+        if (eq < 0)
+            continue;
+        if (part.slice(0, eq).trim() === name)
+            return part.slice(eq + 1).trim();
+    }
+    return undefined;
+}
+/** The Set-Cookie value for a freshly minted session. See the header comment. */
+export function sessionCookie(token, maxAgeMs = SESSION_TTL_MS) {
+    return (`${SESSION_COOKIE}=${token}; Max-Age=${Math.floor(maxAgeMs / 1000)}; ` +
+        `Path=/; HttpOnly; Secure; SameSite=Lax`);
+}
+/**
+ * Strip the link token from a URL so the redirect target is clean.
+ *
+ * The point of the exchange is that the token stops existing in the address bar, in
+ * history, and in anything the browser sends onward. Leaving it on the redirect would
+ * defeat the entire design.
+ */
+export function urlWithoutToken(rawUrl, param) {
+    const url = new URL(rawUrl);
+    url.searchParams.delete(param);
+    const qs = url.searchParams.toString();
+    return url.pathname + (qs ? `?${qs}` : '') + url.hash;
+}

package/dist/doc-system/site/dev-server.d.ts

@@ -38,6 +38,24 @@ export declare function resolveLimitMb(configMb: number | undefined, envMb: stri
  * once per test page (N redundant loads in throwaway frames). An agent only ever
  * drives the top page, so nested frames never need the channel.
  */
+/**
+ * Is this request coming from THIS machine?
+ *
+ * The dev server binds every interface (`Bun.serve` with no `hostname`), which is
+ * deliberate — the mkcert dev cert covers `<host>.local` precisely so you can open the
+ * site on a phone or a second laptop. But "anyone on this network may READ the preview"
+ * and "anyone on this network may REWRITE my source files" are wildly different
+ * propositions, and the source endpoints were getting the first one's treatment.
+ *
+ * On any shared network — a café, a conference, a hotel — an unauthenticated
+ * `POST /__docstore/source` is remote code execution: it writes a file in the repo, the
+ * watcher rebuilds, and the build runs what was written. So those endpoints are
+ * loopback-only, while the site itself stays reachable from your other devices.
+ *
+ * IPv4-mapped IPv6 (`::ffff:127.0.0.1`) counts — that is how a v4 client shows up on a
+ * dual-stack listener, and missing it would lock out the local machine on some setups.
+ */
+export declare function isLoopbackAddress(address: string | undefined | null): boolean;
 export declare function haltijaLoaderSnippet(httpsPort: number): string;
 export declare function devServer(config: SiteConfig, opts?: {
     test?: boolean;