@tilewise/workbench-client 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.2.0 · 2026-11-10 17:08 +04:00
+
+- feat(workbench-client)!: serve the dev server over https by default, for Safari (4219956)
+  - Serve https with a certificate for localhost from Vite's own @vitejs/plugin-basic-ssl, one for every project on the computer, kept in
+  - Add the https option and WORKBENCH_HTTPS (1 or 0) to choose, keeping an app's own server.https, and http under Vitest
+  - Log how to trust the certificate on a Mac and on Windows at each start
+  - Link the viewer to the dev server's https address
+  - Describe https in the README
+  - BREAKING CHANGE: the dev server answers on https://localhost:<port> instead of http://localhost:<port>; set https: false or WORKBENCH_HTTPS=0 to keep http
+- fix(workbench-client): leave out HTTP/2 pseudo-headers when asking a fake API (a326e03)
+  - Skip :method, :path and the other pseudo-headers a request over HTTP/2 carries, which fetch refuses, so a dev server on https answers /api
+  - Leave out keep-alive, upgrade and proxy-connection from a fake API's answer, which HTTP/2 refuses
+  - Test a request as HTTP/2 hands it over
+- feat(workbench-client): hand the dev server's token to the viewer's origin at /connect (0ab508c)
+  - Add GET /__workbench/connect, which answers { token, repo } to a request from an allowed origin (WORKBENCH_URL or a viewer on localhost) and nothing
+  - Read the repository's owner/name in one helper, for the link and /connect
+  - Test that only the viewer's origin gets the token
+  - Describe connecting in the README
+
 ## 0.1.2 · 2026-11-07 06:11 +04:00
 
 - feat(workbench-client): read the fake API from workbench.json (25e1ad9)

package/README.md

@@ -181,8 +181,35 @@ repository declares its setup: the fake API comes from it (below), and
 read it from GitHub.
 
 Only the viewer may ask: from its origin (`WORKBENCH_URL`, or a viewer on
-localhost) with the token in the link the dev server logs. `pnpm dev` opens
-that link; without `WORKBENCH_URL` the dev server opens no viewer.
+localhost) with the dev server's token. The viewer has it from the link the
+dev server logs, which `pnpm dev` opens, or by connecting to the dev server's
+port: `/__workbench/connect` hands the token, and the repository it serves,
+to a page of those origins alone, as the browser names a page's origin and
+no site can claim another's. Without `WORKBENCH_URL` the dev server opens no
+viewer, and only a viewer on localhost can connect.
+
+### https
+
+The dev server serves https, so Safari can use Local too. Safari blocks a
+secure page, as the viewer is, from reaching `http://localhost`, which
+Chrome and Firefox allow. The certificate comes from Vite's own
+[`@vitejs/plugin-basic-ssl`](https://github.com/vitejs/vite-plugin-basic-ssl).
+It is made for localhost, one for every project on the computer, and kept in
+`~/.workbench/https` for 825 days, Apple's limit.
+
+Each computer trusts it once, as the dev server's log says at each start:
+
+- **Mac** (Safari, and Chrome with it): open `https://localhost:5173` in
+  Safari, choose *Show Details* › *visit this website*, and enter your
+  password.
+- **Windows** (Chrome and Edge):
+  `certutil -user -addstore TrustedPeople "%USERPROFILE%\.workbench\https\localhost.crt"`.
+  TrustedPeople trusts this certificate alone, never one it signs.
+
+`https: false` in the options, or `WORKBENCH_HTTPS=0`, serves http.
+`WORKBENCH_HTTPS=1` serves https whatever the options say. An app that sets
+its own `server.https` keeps it. Under Vitest it is http, unless `https` is
+set.
 
 ### An app in a workspace
 

package/dist/vite/environment.d.ts

@@ -4,6 +4,10 @@ export declare const environment: {
     viewerUrl: string | null;
     /** The package script that started the dev server: only `dev` opens the viewer. */
     script: string | null;
+    /** WORKBENCH_HTTPS: `1` serves https, `0` http; unset leaves it to the option. */
+    https: boolean | null;
+    /** Run by Vitest, whose servers are never opened in a browser. */
+    vitest: boolean;
 };
 /** What a build's install and bundle run with: this environment, as CI. */
 export declare const buildEnvironment: () => NodeJS.ProcessEnv;

package/dist/vite/environment.js

@@ -1,10 +1,15 @@
 const viewer = process.env['WORKBENCH_URL']?.replace(/\/$/, '');
+const https = process.env['WORKBENCH_HTTPS'];
 /** Every setting the local builds service reads from the environment. */
 export const environment = {
     /** The viewer's address. Without it, the dev server opens no viewer. */
     viewerUrl: viewer === undefined || viewer === '' ? null : viewer,
     /** The package script that started the dev server: only `dev` opens the viewer. */
     script: process.env['npm_lifecycle_event'] ?? null,
+    /** WORKBENCH_HTTPS: `1` serves https, `0` http; unset leaves it to the option. */
+    https: https === '1' ? true : https === '0' ? false : null,
+    /** Run by Vitest, whose servers are never opened in a browser. */
+    vitest: !!process.env['VITEST'],
 };
 /** What a build's install and bundle run with: this environment, as CI. */
 export const buildEnvironment = () => ({ ...process.env, CI: '1' });

package/dist/vite/fetchBridge.d.ts

@@ -1,7 +1,9 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 /**
  * A Node request as a fetch `Request` for a fake API, at `path`: the part of
- * the address after the API's mount, with its query.
+ * the address after the API's mount, with its query. HTTP/2's pseudo-headers
+ * (`:method`, `:path`…), which the https dev server's requests carry, are
+ * no headers to fetch, so they are left out.
  */
 export declare function toRequest(request: IncomingMessage, path: string): Promise<Request>;
 /** Writes a fake API's fetch `Response` to a Node response. */

package/dist/vite/fetchBridge.js

@@ -1,5 +1,12 @@
-/** Headers Node works out for itself, from what it sends. */
-const COMPUTED = new Set(['content-length', 'transfer-encoding', 'connection']);
+/** Headers Node works out for itself, from what it sends, and that HTTP/2 refuses. */
+const COMPUTED = new Set([
+    'content-length',
+    'transfer-encoding',
+    'connection',
+    'keep-alive',
+    'upgrade',
+    'proxy-connection',
+]);
 const bodyOf = (request) => {
     return new Promise((resolve, reject) => {
         const chunks = [];
@@ -10,13 +17,15 @@ const bodyOf = (request) => {
 };
 /**
  * A Node request as a fetch `Request` for a fake API, at `path`: the part of
- * the address after the API's mount, with its query.
+ * the address after the API's mount, with its query. HTTP/2's pseudo-headers
+ * (`:method`, `:path`…), which the https dev server's requests carry, are
+ * no headers to fetch, so they are left out.
  */
 export async function toRequest(request, path) {
     const method = request.method ?? 'GET';
     const headers = new Headers();
     for (const [name, value] of Object.entries(request.headers)) {
-        if (value === undefined) {
+        if (value === undefined || name.startsWith(':')) {
             continue;
         }
         for (const each of Array.isArray(value) ? value : [value]) {

package/dist/vite/git.d.ts

@@ -5,3 +5,5 @@ export declare function gitIn(root: string): Git;
 export declare const refExists: (git: Git, ref: string) => Promise<boolean>;
 /** The repository's default branch, as its remote has it, or `main`. */
 export declare function defaultBranch(git: Git): Promise<string>;
+/** The repository on GitHub, as `owner/name`, from its `origin` remote; null for any other. */
+export declare function repositoryOf(git: Git): Promise<string | null>;

package/dist/vite/git.js

@@ -16,3 +16,8 @@ export async function defaultBranch(git) {
     const head = await git('symbolic-ref', '--short', 'refs/remotes/origin/HEAD').catch(() => '');
     return head.trim().replace(/^origin\//, '') || 'main';
 }
+/** The repository on GitHub, as `owner/name`, from its `origin` remote; null for any other. */
+export async function repositoryOf(git) {
+    const remote = await git('remote', 'get-url', 'origin').catch(() => '');
+    return /github\.com[:/]([\w.-]+\/[\w.-]+?)(?:\.git)?\s*$/.exec(remote)?.[1] ?? null;
+}

package/dist/vite/https.d.ts

@@ -0,0 +1,17 @@
+export interface Certificate {
+    /** The key and the certificate, as Vite's `server.https` takes them. */
+    pem: string;
+    /** The certificate alone, the file a browser is told to trust. */
+    file: string;
+}
+/**
+ * The dev server's certificate for localhost, made by Vite's own basic-ssl.
+ * One for every project on this computer, kept in `~/.workbench/https` for
+ * 825 days, so a browser trusts it once. `folder` is for tests.
+ */
+export declare function localhostCertificate(folder?: string): Promise<Certificate>;
+/**
+ * How to trust the certificate, once per computer, for the dev server's log
+ * at each start: whether this computer trusts it can't be told from here.
+ */
+export declare function trustSteps(file: string, port: number): string[];

package/dist/vite/https.js

@@ -0,0 +1,34 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { getCertificate } from '@vitejs/plugin-basic-ssl';
+/** Apple's longest lifetime for a certificate its browsers trust. */
+const DAYS = 825;
+const CERTIFICATE = /-----BEGIN CERTIFICATE-----[\s\S]+?-----END CERTIFICATE-----/;
+/**
+ * The dev server's certificate for localhost, made by Vite's own basic-ssl.
+ * One for every project on this computer, kept in `~/.workbench/https` for
+ * 825 days, so a browser trusts it once. `folder` is for tests.
+ */
+export async function localhostCertificate(folder = join(homedir(), '.workbench', 'https')) {
+    const pem = await getCertificate(folder, 'localhost', [], DAYS);
+    const file = join(folder, 'localhost.crt');
+    const certificate = CERTIFICATE.exec(pem)?.[0] ?? '';
+    const kept = await readFile(file, 'utf8').catch(() => '');
+    if (kept.trim() !== certificate) {
+        await mkdir(folder, { recursive: true });
+        await writeFile(file, `${certificate}\n`);
+    }
+    return { pem, file };
+}
+/**
+ * How to trust the certificate, once per computer, for the dev server's log
+ * at each start: whether this computer trusts it can't be told from here.
+ */
+export function trustSteps(file, port) {
+    return [
+        'HTTPS: trust its certificate once on this computer, if you haven’t yet.',
+        `  Mac: open https://localhost:${port} in Safari, choose Show Details › visit this website, and enter your password`,
+        `  Windows: certutil -user -addstore TrustedPeople "${file}"`,
+    ];
+}

package/dist/vite/workbenchLocal.d.ts

@@ -4,6 +4,7 @@ import type { Plugin } from 'vite';
  * also answers the deployed viewer. It lists this machine's branches and
  * commits, builds any commit, and checks a branch out.
  *
+ *   GET  /__workbench/connect            { token, repo }: the token, for an allowed origin, which needs none
  *   GET  /__workbench/setup              the checkout's workbench.json: { name, viewers }; 404 none, 422 no setup
  *   GET  /__workbench/versions           branches, tags, what is checked out, changed files
  *   GET  /__workbench/commits?ref=<ref>  that ref's history, newest first, each with its build
@@ -17,6 +18,11 @@ import type { Plugin } from 'vite';
  * default branch unless set. Builds are served without the token, as a frame
  * can't send a header. Without WORKBENCH_URL, the dev server opens no viewer.
  *
+ * The viewer has the token from the link the dev server logs, or asks
+ * `/connect` for it from its own page. Only a page of an allowed origin gets
+ * it: the browser names the page's origin, and no site can claim another's. A
+ * request that names none, as a page's request to its own origin, gets none.
+ *
  * A fake API beside the app is declared in `workbench.json` at the
  * repository's top, as Proto's `api`: its module from Proto's `folder`, whose
  * default export is a fetch handler, asked at `/api`. The dev server answers
@@ -28,6 +34,13 @@ import type { Plugin } from 'vite';
  *
  * The `api` option overrides the file: `entry`, the module from the app's
  * folder, and `path`, where the app asks it (`/api` unless set).
+ *
+ * The dev server serves https, so Safari, which blocks a secure page from
+ * reaching `http://localhost`, can use it too. Its certificate is Vite's own
+ * basic-ssl's, one for every project on this computer, which a browser
+ * trusts once (https.ts). `https: false`, or WORKBENCH_HTTPS=0, serves http;
+ * WORKBENCH_HTTPS=1 serves https whatever the option says. Under Vitest it is
+ * http unless `https` is set, and an app's own `server.https` is left as is.
  */
 export declare function workbenchLocal(options?: {
     base?: string;
@@ -35,4 +48,5 @@ export declare function workbenchLocal(options?: {
         entry: string;
         path?: string;
     };
+    https?: boolean;
 }): Plugin;

package/dist/vite/workbenchLocal.js

@@ -7,7 +7,8 @@ import { createBuilds } from './builds.js';
 import { checkout } from './checkout.js';
 import { environment } from './environment.js';
 import { sendResponse, toRequest } from './fetchBridge.js';
-import { defaultBranch, gitIn } from './git.js';
+import { defaultBranch, gitIn, repositoryOf } from './git.js';
+import { localhostCertificate, trustSteps } from './https.js';
 import { sendJson, serveBuild } from './serveBuild.js';
 import { readSetup, setupApi } from './setup.js';
 import { commits, versions } from './versions.js';
@@ -59,6 +60,7 @@ function open(url) {
  * also answers the deployed viewer. It lists this machine's branches and
  * commits, builds any commit, and checks a branch out.
  *
+ *   GET  /__workbench/connect            { token, repo }: the token, for an allowed origin, which needs none
  *   GET  /__workbench/setup              the checkout's workbench.json: { name, viewers }; 404 none, 422 no setup
  *   GET  /__workbench/versions           branches, tags, what is checked out, changed files
  *   GET  /__workbench/commits?ref=<ref>  that ref's history, newest first, each with its build
@@ -72,6 +74,11 @@ function open(url) {
  * default branch unless set. Builds are served without the token, as a frame
  * can't send a header. Without WORKBENCH_URL, the dev server opens no viewer.
  *
+ * The viewer has the token from the link the dev server logs, or asks
+ * `/connect` for it from its own page. Only a page of an allowed origin gets
+ * it: the browser names the page's origin, and no site can claim another's. A
+ * request that names none, as a page's request to its own origin, gets none.
+ *
  * A fake API beside the app is declared in `workbench.json` at the
  * repository's top, as Proto's `api`: its module from Proto's `folder`, whose
  * default export is a fetch handler, asked at `/api`. The dev server answers
@@ -83,12 +90,21 @@ function open(url) {
  *
  * The `api` option overrides the file: `entry`, the module from the app's
  * folder, and `path`, where the app asks it (`/api` unless set).
+ *
+ * The dev server serves https, so Safari, which blocks a secure page from
+ * reaching `http://localhost`, can use it too. Its certificate is Vite's own
+ * basic-ssl's, one for every project on this computer, which a browser
+ * trusts once (https.ts). `https: false`, or WORKBENCH_HTTPS=0, serves http;
+ * WORKBENCH_HTTPS=1 serves https whatever the option says. Under Vitest it is
+ * http unless `https` is set, and an app's own `server.https` is left as is.
  */
 export function workbenchLocal(options = {}) {
     let root = process.cwd();
     let git = gitIn(root);
     let top = null;
     let server = null;
+    let certificate = null;
+    const https = environment.https ?? options.https ?? !environment.vitest;
     const given = options.api;
     const option = given
         ? {
@@ -218,6 +234,9 @@ export function workbenchLocal(options = {}) {
             response.statusCode = 204;
             return response.end();
         }
+        if (request.method === 'GET' && url.pathname === '/connect' && allowed(origin)) {
+            return sendJson(response, 200, { token, repo: await repositoryOf(git) });
+        }
         if (!allowed(origin) || request.headers['x-workbench-token'] !== token) {
             return sendJson(response, 403, {
                 error: 'Only the viewer, with the token from the dev server',
@@ -233,8 +252,15 @@ export function workbenchLocal(options = {}) {
     return {
         name: 'workbench-local',
         apply: 'serve',
-        // Builds and their worktrees are no part of the app: never watch or reload for them.
-        config: () => ({ server: { watch: { ignored: ['**/.builds/**'] } } }),
+        async config(config) {
+            // Builds and their worktrees are no part of the app: never watch or reload for them.
+            const ignored = { watch: { ignored: ['**/.builds/**'] } };
+            if (!https || config.server?.https) {
+                return { server: ignored };
+            }
+            certificate = await localhostCertificate();
+            return { server: { ...ignored, https: { key: certificate.pem, cert: certificate.pem } } };
+        },
         configResolved(config) {
             root = config.root;
             git = gitIn(root);
@@ -266,16 +292,20 @@ export function workbenchLocal(options = {}) {
         },
     };
     async function announce(devServer) {
+        const address = devServer.httpServer?.address();
+        const port = typeof address === 'object' && address ? address.port : 5173;
+        // How to trust the certificate, once, before the viewer is opened on it.
+        if (certificate) {
+            devServer.config.logger.info(`\n  ${trustSteps(certificate.file, port).join('\n  ')}`);
+        }
         if (!environment.viewerUrl) {
             devServer.config.logger.info('\n  Viewer: set WORKBENCH_URL to its address to open it\n');
             return;
         }
-        const address = devServer.httpServer?.address();
-        const port = typeof address === 'object' && address ? address.port : 5173;
         // The repository, as owner/name: the viewer opens its project from it.
-        const remote = await git('remote', 'get-url', 'origin').catch(() => '');
-        const repository = /github\.com[:/]([\w.-]+\/[\w.-]+?)(?:\.git)?\s*$/.exec(remote)?.[1];
-        const local = encodeURIComponent(`http://localhost:${port}`);
+        const repository = await repositoryOf(git);
+        const scheme = devServer.config.server.https ? 'https' : 'http';
+        const local = encodeURIComponent(`${scheme}://localhost:${port}`);
         const url = `${environment.viewerUrl}/?src=local&v=live#local=${local}&token=${token}${repository ? `&repo=${encodeURIComponent(repository)}` : ''}`;
         devServer.config.logger.info(`\n  Viewer: ${url}\n`);
         // `pnpm dev` opens it; any other script is the app alone.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tilewise/workbench-client",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Connects a React prototype to the workbench's viewer: its screens, its controls and the protocol between them.",
   "license": "MIT",
   "repository": {
@@ -54,6 +54,7 @@
     "vitest": "^4.1.11"
   },
   "dependencies": {
+    "@vitejs/plugin-basic-ssl": "^2.3.0",
     "modern-screenshot": "^4.7.0"
   },
   "scripts": {