tosijs-ui 1.9.0-beta.1 → 1.9.0-beta.2

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # 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

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-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.js

@@ -15,6 +15,7 @@ import { buildSite } from './orchestrator';
 import { preflight } from './preflight';
 import { auditDependencies, reportAudit } from './audit-guard';
 import { openDevBrowser } from './open-browser';
+import { createAuthState, issueLink, readCookie, redeemLink, sessionCookie, urlWithoutToken, validSession, SESSION_COOKIE, } from './dev-auth';
 const TEST_RESULTS_FILE = '.browser-tests.json';
 const DEFAULT_IDLE_HOURS = 8;
 /**
@@ -310,6 +311,28 @@ export async function devServer(config, opts = {}) {
     statusSnippet() below and the `__tosiDevStatus` reader in doc-browser.ts.
     */
     let buildStatus = { ok: true };
+    /*
+    Magic-link auth, so a workspace exposed via `bun run tunnel` can be edited from
+    anywhere. A LINK token rides in a URL and is spent on first use; it is exchanged for
+    a durable SESSION cookie that never appears in a URL. See dev-auth.ts for why that
+    asymmetry is the whole design.
+  
+    In memory on purpose: a dev server restart invalidating sessions is a feature, not a
+    gap — the credential's lifetime should not outlive the process that granted it, and
+    re-linking is one command.
+    */
+    const auth = createAuthState();
+    const LINK_PARAM = 't';
+    /** Print a fresh single-use link. Called on demand (SIGUSR2) and by --link. */
+    const printLink = () => {
+        const token = issueLink(auth, Date.now());
+        const base = config.preview?.tunnel?.url ?? `https://localhost:${PORT}`;
+        const url = `${base}/?${LINK_PARAM}=${token}`;
+        console.log(`\n🔗 Single-use edit link (valid 15 min, then it is spent):\n   ${url}\n`);
+        return url;
+    };
+    // `kill -USR2 <pid>` prints a fresh link without restarting the server.
+    process.on('SIGUSR2', () => printLink());
     let testReportResolve;
     // Source read/write for in-browser "edit page source" (config.editableSources).
     // Local dev only — your machine, your files — so the lone guard is correctness:
@@ -746,6 +769,88 @@ export async function devServer(config, opts = {}) {
         },
         async fetch(request, srv) {
             touch();
+            /*
+            TWO POSTURES, because projects differ.
+      
+            DEFAULT — read open, write gated. Without a session the site RENDERS: read the
+            docs, click around, run live examples. You just cannot change anything. This is
+            usually what you want, for two reasons: the read-only view is the thing you most
+            often hand someone, and an expired link degrades to a readable page rather than a
+            wall — which matters when you already hold a session and open a second window or
+            a second device.
+      
+            `tunnel.requireToken: true` — locked. No session, nothing at all, including the
+            page. For work that must not be readable by whoever finds the hostname.
+      
+            Either way WRITES always need a session (see /__docstore/source below). The
+            option only moves where READING sits.
+            */
+            /*
+            Magic-link exchange. A `?t=` on ANY path is spent immediately for a session
+            cookie, then we 302 to the same URL with the token stripped.
+      
+            Redirecting is not cosmetic: it is what stops the token existing in the address
+            bar, in history, and in the Referer of anything the page subsequently loads.
+            `Referrer-Policy: no-referrer` covers the one request that DID carry it.
+      
+            An invalid or already-spent token is not an error — it just falls through
+            unauthenticated, so a stale link behaves like no link rather than leaking whether
+            that token was ever real.
+            */
+            const reqUrl = new URL(request.url);
+            const linkToken = reqUrl.searchParams.get(LINK_PARAM);
+            /*
+            PROXIED REQUESTS NEED A SESSION FOR EVERYTHING, not just for writing.
+      
+            The workspace mirrors dev, so it carries unreleased work — viewing it is as
+            private as editing it. Gating only the write endpoint would have left the whole
+            site readable to anyone who found the hostname.
+      
+            This is also what removes the basic-auth dialog. Putting basicauth in front
+            defeated the point of a magic link: you clicked the link and the browser asked
+            for a password anyway. One credential, one prompt-free click.
+      
+            Redemption itself must stay reachable without a session — it is how you GET one.
+            Direct (unproxied) requests are unaffected: at this keyboard, the site is just
+            the dev server it has always been.
+            */
+            const viaProxy = request.headers.get('x-forwarded-for') !== null ||
+                request.headers.get('x-forwarded-host') !== null;
+            const lockedDown = config.preview?.tunnel?.requireToken === true;
+            if (lockedDown && viaProxy && !linkToken) {
+                const cookie = readCookie(request.headers.get('cookie'), SESSION_COOKIE);
+                if (!validSession(auth, cookie, Date.now())) {
+                    return new Response(`<!doctype html><meta charset=utf-8>` +
+                        `<title>Link required</title>` +
+                        `<style>body{font:16px/1.6 system-ui;margin:15vh auto;max-width:30rem;padding:0 1.5rem;color:#222}` +
+                        `@media(prefers-color-scheme:dark){body{background:#16171a;color:#e8e8ea}}` +
+                        `code{background:#8881;padding:.1em .4em;border-radius:4px}</style>` +
+                        `<h1>This workspace needs an invite link</h1>` +
+                        `<p>Ask for a fresh one — they are single-use and expire after 15 minutes.</p>` +
+                        `<p><code>bun run tunnel --link</code></p>`, {
+                        status: 401,
+                        headers: {
+                            'Content-Type': 'text/html; charset=utf-8',
+                            'Cache-Control': 'no-store',
+                            'Referrer-Policy': 'no-referrer',
+                        },
+                    });
+                }
+            }
+            if (linkToken) {
+                const session = redeemLink(auth, linkToken, Date.now());
+                const clean = urlWithoutToken(request.url, LINK_PARAM);
+                const headers = {
+                    Location: clean,
+                    'Referrer-Policy': 'no-referrer',
+                    'Cache-Control': 'no-store',
+                };
+                if (session) {
+                    headers['Set-Cookie'] = sessionCookie(session);
+                    console.log('🔓 edit link redeemed — session issued');
+                }
+                return new Response(null, { status: 302, headers });
+            }
             let reqPath = new URL(request.url).pathname;
             console.log(request.method, reqPath);
             if (request.method === 'POST' && reqPath === '/report') {
@@ -764,22 +869,52 @@ export async function devServer(config, opts = {}) {
                 if (!config.editableSources) {
                     return new Response('editableSources is not enabled in this doc-site config (set editableSources: true to edit/save source in dev)', { status: 501, headers: { 'Content-Type': 'text/plain; charset=utf-8' } });
                 }
-                // LOOPBACK ONLY. Reading exposes any file in the repo; writing is remote code
-                // execution (write a file, the watcher rebuilds, the build runs it). Checked on
-                // the PEER ADDRESS, never on Origin/Host, which are attacker-supplied.
-                //
-                // There is deliberately NO override. An env var that re-enables this would have
-                // no legitimate use today — nothing authenticates in front of this server — and
-                // it is exactly the shape of guard that gets set once in a shell profile and
-                // stays off forever. Remote editing is not a flag to flip; it needs real
-                // authentication, and that is Phase 3 of REMOTE-ACCESS-PLAN.md, where the
-                // schema is the authorization boundary and a session (not a location, and not
-                // an env var) decides who may write. Until then: view remotely, edit locally.
+                /*
+                LOOPBACK **OR** AN AUTHENTICATED SESSION.
+        
+                Reading serves any file in the repo; writing is remote code execution (write a
+                file, the watcher rebuilds, the build runs it). So the caller must be one of:
+        
+                  - physically local (you, at this keyboard), or
+                  - holding a session cookie earned by spending a single-use link.
+        
+                Note there is still no env-var override and no token read from a URL or a
+                header a page could forge: the session arrives as an HttpOnly cookie the
+                browser attaches itself, and SameSite=Lax means another origin cannot make
+                your browser POST here with it. A location check alone was a stopgap; this is
+                the actual authorization.
+                */
                 const peer = srv?.requestIP?.(request)?.address;
-                if (!isLoopbackAddress(peer)) {
+                const session = readCookie(request.headers.get('cookie'), SESSION_COOKIE);
+                /*
+                A TUNNELLED REQUEST LOOKS LOOPBACK, so the peer address alone cannot be trusted
+                here. `ssh -R` delivers to localhost, so every remote request arriving through
+                the tunnel has a 127.0.0.1 peer — meaning a naive `loopback OR session` lets
+                anyone past the proxy write files WITHOUT a session, and the cookie buys
+                nothing. (Caught by a test that did exactly that.)
+        
+                So split on whether the request was PROXIED. Caddy's reverse_proxy sets
+                X-Forwarded-*; a browser on this machine talking to the dev server directly
+                does not. Therefore:
+        
+                  proxied  → a valid session is REQUIRED (loopback is meaningless here)
+                  direct   → loopback peer is sufficient (you are at this keyboard)
+        
+                Trusting a header is normally a mistake, and it is safe here only because of
+                the topology: the tunnel's remote end is bound to the box's loopback
+                (`GatewayPorts no`), so nothing reaches this socket from outside except through
+                Caddy — which sets the header itself. A remote caller cannot arrive without it.
+                And forging it can only ever make the check STRICTER, never weaker.
+                */
+                const proxied = request.headers.get('x-forwarded-for') !== null ||
+                    request.headers.get('x-forwarded-host') !== null;
+                const authorized = proxied
+                    ? validSession(auth, session, Date.now())
+                    : isLoopbackAddress(peer);
+                if (!authorized) {
                     console.warn(`⚠️  refused ${request.method} /__docstore/source from ${peer ?? 'unknown'} — ` +
-                        `source editing is local-only.`);
-                    return new Response('source editing is restricted to this machine', {
+                        `no session (use \`bun run tunnel --link\` for an edit link).`);
+                    return new Response('not authorized to edit source', {
                         status: 403,
                         headers: { 'Content-Type': 'text/plain; charset=utf-8' },
                     });

package/dist/doc-system/site/site-config.d.ts

@@ -315,6 +315,38 @@ export interface SiteConfig {
         path?: string;
         /** public URL, printed after a successful deploy (e.g. `https://dev.example.com`) */
         url?: string;
+        /**
+         * Expose THIS machine's dev server at an authenticated public URL, via an SSH
+         * reverse tunnel to `host` (`bun run tunnel`).
+         *
+         * The box does no compute — it terminates TLS and checks a password. The work
+         * stays where the data is, which is what lets one small VPS serve many projects.
+         *
+         * Safe to expose despite the dev server's source endpoints being loopback-only:
+         * the box's sshd runs `GatewayPorts no`, so the forwarded port is bound to its
+         * loopback and only the authenticating proxy can reach it — and `ssh -R` delivers
+         * to `localhost` here, so the dev server sees a loopback peer. Reaching that
+         * socket at all required passing the front door.
+         */
+        tunnel?: {
+            /** port to bind on the remote box (loopback there); default 9787 */
+            remotePort?: number;
+            /** the authenticated public URL that fronts it */
+            url?: string;
+            /**
+             * Require a valid session even to VIEW the tunnelled workspace.
+             *
+             * Default `false`: the site renders for anyone who has the URL, but **writes
+             * always need a session** — so a stranger sees a read-only page and cannot
+             * change anything. That is usually right, and it means an expired link degrades
+             * to a readable page instead of a wall (which matters when you already hold a
+             * session and open a second window or another device).
+             *
+             * Set `true` for maximum security: no session, nothing at all — not even the
+             * page. Use it when the work must not be readable by whoever finds the hostname.
+             */
+            requireToken?: boolean;
+        };
     };
     /**
      * Enable the dev-server source read/write endpoints (`/__docstore/source`) that