@blakearoberts/visage 0.0.1-rc.26 → 0.0.1-rc.27

package/README.md

@@ -1,6 +1,7 @@
 # Visage
 
-Visage (`/vit·ɛdʒ/`) is a Vite plugin for local development with HMR and OIDC session cookie lifecycle semantics.
+Visage (`/vit·ɛdʒ/`) is a Vite plugin for local development with HMR and OIDC
+session cookie lifecycle semantics.
 
 ## Getting Started
 
@@ -27,21 +28,32 @@ Start Vite normally:
 vite
 ```
 
-By default, you can reach the app at `https://localhost:9001`. You will be redirected to Dex to sign in. The default username and password is `user@example.com` and `pass`.
+By default, you can reach the app at `https://localhost:9001`. You will be
+redirected to Dex to sign in. The default username and password is
+`user@example.com` and `pass`.
 
 ## Why Visage
 
-Visage is a local development harness for web apps that run behind an auth-protected edge, where browser sessions are represented by secure cookies backed by OIDC tokens.
+Visage is a local development harness for web apps that run behind an
+auth-protected edge, where browser sessions are represented by secure cookies
+backed by OIDC tokens.
 
-Visage narrows the gap between local development, automated tests, and production by bringing production-like session lifecycle semantics to local Vite development without giving up HMR. That makes it practical to iterate on SSR identity injection, session timeout recovery, lock screens, and authenticated API calls.
+Visage narrows the gap between local development, automated tests, and
+production by bringing production-like session lifecycle semantics to local Vite
+development without giving up HMR. That makes it practical to iterate on SSR
+identity injection, session timeout recovery, lock screens, and authenticated
+API calls.
 
-Visage can also use a hosted IdP, so local frontend code can call hosted backend APIs with real credentials. That avoids frontend-only auth mocks or backend-only local bypasses: code can be written for production and still work locally.
+Visage can also use a hosted IdP, so local frontend code can call hosted backend
+APIs with real credentials. That avoids frontend-only auth mocks or backend-only
+local bypasses: code can be written for production and still work locally.
 
 ## Configuration
 
 Visage is configured through `visage(options?)` in `vite.config.ts`.
 
-The top-level `host` and `port` configure the local Visage origin that the browser visits:
+The top-level `host` and `port` configure the local Visage origin that the
+browser visits:
 
 ```ts
 visage({ host: 'localhost', port: 9001 });
@@ -94,8 +106,7 @@ visage({
 ```
 
 OAuth2 Proxy identity values can also be mapped explicitly through headers such
-as `$auth_user`, `$auth_email`, `$auth_groups`, and
-`$auth_preferred_username`.
+as `$auth_user`, `$auth_email`, `$auth_groups`, and `$auth_preferred_username`.
 
 Authenticated locations also get Fetch Metadata CSRF checks by default. The
 built-in Vite root location uses `csrf: 'app'`, which allows same-origin
@@ -141,15 +152,12 @@ flowchart LR
 
 ## Required Tools
 
-- [Docker](https://docs.docker.com/get-started/get-docker/) with Compose v2 support through `docker compose`.
+- [Docker](https://docs.docker.com/get-started/get-docker/) with Compose v2
+  support through `docker compose`.
+- [`mkcert`](https://github.com/FiloSottile/mkcert#installation) installed on
+  `PATH`, or configured with `VISAGE_MKCERT=/path/to/mkcert`.
 
-## Managed Tools
-
-### mkcert
-
-Visage downloads [`mkcert`](https://github.com/FiloSottile/mkcert) from `dl.filippo.io` into `$XDG_CACHE_HOME/visage/bin/mkcert-<platform>-<arch>` when the Vite dev server starts. Visage uses it to install a local certificate authority and generate HTTPS certificates for the local proxy.
-
-### Docker Images
+## Managed Docker Images
 
 Visage pulls these as needed based on configuration:
 
@@ -161,9 +169,15 @@ Visage pulls these as needed based on configuration:
 
 ## Security Notes
 
-Visage is local-development tooling. It starts local auth infrastructure, terminates local HTTPS, and forwards authenticated identity or token material to configured upstreams.
+Visage is local-development tooling. It starts local auth infrastructure,
+terminates local HTTPS, and forwards authenticated identity or token material to
+configured upstreams.
+
+Please report suspected vulnerabilities through GitHub private vulnerability
+reporting as described in [Security Policy](SECURITY.md).
 
-Do not treat the managed Dex and OAuth2 Proxy defaults as production auth infrastructure.
+Do not treat the managed Dex and OAuth2 Proxy defaults as production auth
+infrastructure.
 
 Visage's CSRF policy is an edge request-isolation guard for cookie-backed
 locations. It is not a replacement for application-owned CSRF tokens where an
@@ -172,14 +186,19 @@ application accepts form posts or other browser-submitted mutations. CSP,
 
 ## Troubleshooting
 
-- If startup fails immediately, confirm Docker is running and `docker compose` works.
+- If startup fails immediately, confirm Docker is running and `docker compose`
+  works.
 - If NGINX cannot start, check whether the configured `port` is already in use.
-- If the hostname cannot be resolved, Visage may need permission to update `/etc/hosts`.
-- If the browser rejects the certificate, allow the local certificate authority prompt from `mkcert`; CI test runners should be configured to ignore local HTTPS errors.
+- If the hostname cannot be resolved, Visage may need permission to update
+  `/etc/hosts`.
+- If the browser rejects the certificate, allow the local certificate authority
+  prompt from `mkcert`; CI test runners should be configured to ignore local
+  HTTPS errors.
 
 ## TO-DO
 
-- [ ] Harden the default security posture by addressing the [security hardening backlog](docs/security-hardening.md).
+- [ ] Harden the default security posture by addressing the
+      [security hardening backlog](docs/security-hardening.md).
 - [ ] Support configuring [Dex connectors](https://dexidp.io/docs/connectors/).
 - [ ] Support configuring Dex on a distinct subdomain, such as `auth.localhost`.
 - [ ] Support optional [HTTP mode without local TLS](docs/tls-http-mode.md).

package/dist/certs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"certs.d.ts","sourceRoot":"","sources":["../src/certs.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAI7C,wBAAsB,WAAW,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAuCrE"}
+{"version":3,"file":"certs.d.ts","sourceRoot":"","sources":["../src/certs.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAI7C,wBAAsB,WAAW,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAwCrE"}

package/dist/index.js

@@ -2,11 +2,9 @@ import { spawnSync, spawn } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import { isIP } from 'node:net';
 import { join } from 'node:path';
-import { readFileSync, mkdirSync, chmodSync, openSync, rmSync, existsSync, createWriteStream, appendFileSync, writeFileSync } from 'node:fs';
+import { readFileSync, mkdirSync, chmodSync, openSync, rmSync, appendFileSync, writeFileSync } from 'node:fs';
 import { parse, stringify } from 'yaml';
 import { homedir } from 'node:os';
-import { Readable } from 'node:stream';
-import { pipeline } from 'node:stream/promises';
 import { hashSync } from 'bcryptjs';
 import { Eta } from 'eta';
 
@@ -465,13 +463,14 @@ async function ensureCerts(config) {
     const CAROOT = join(CACHE_HOME, 'visage/ca');
     mkdirSync(CAROOT, { recursive: true, mode: 0o700 });
     chmodSync(CAROOT, 0o700);
-    const mkcert = await ensureMkCert();
+    const mkcert = resolveMkcert();
     const out = openSync(join(config.cache, 'logs', 'mkcert.log'), 'w');
     const env = { CAROOT, TRUST_STORES: 'system', ...process.env };
     const tty = process.stdin.isTTY;
     const stdio = [tty ? 'inherit' : 'ignore', out, out];
     if (process.env.CI !== 'true') {
-        // mkcert -install is idempotent; CA files alone do not prove trust-store state.
+        // mkcert -install is idempotent;
+        // CA files alone don't prove trust-store state.
         const result = spawnSync(mkcert, ['-install'], { env, stdio });
         if (result.error)
             throw result.error;
@@ -497,23 +496,77 @@ async function ensureCerts(config) {
     chmodSync(cert, 0o600);
     chmodSync(key, 0o600);
 }
-async function ensureMkCert() {
-    const bin = join(CACHE_HOME, 'visage/bin');
-    const file = join(bin, `mkcert-${process.platform}-${process.arch}`);
-    if (existsSync(file))
-        return file;
-    mkdirSync(bin, { recursive: true });
-    const base = 'https://dl.filippo.io/mkcert/latest';
-    const arch = process.arch === 'x64' ? 'amd64' : process.arch;
-    const params = `?for=${process.platform}/${arch}`;
-    const url = new URL(params, base);
-    const response = await fetch(url);
-    if (!response.ok || !response.body) {
-        throw new Error('Failed to download mkcert');
+function resolveMkcert() {
+    const env = process.env;
+    const options = { encoding: 'utf8', env };
+    const mkcert = findMkcert();
+    const result = spawnSync(mkcert, ['-version'], options);
+    if (result.error || result.status !== 0) {
+        throw new Error([
+            `Visage found mkcert at "${mkcert}", but could not execute it.`,
+            '',
+            mkcertInstallInstructions(),
+        ].join('\n'));
     }
-    await pipeline(Readable.fromWeb(response.body), createWriteStream(file));
-    chmodSync(file, 0o755);
-    return file;
+    return mkcert;
+}
+function findMkcert() {
+    const env = process.env;
+    const exec = env.VISAGE_MKCERT || 'mkcert';
+    const options = { encoding: 'utf8', env };
+    const result = process.platform === 'win32'
+        ? spawnSync('where', [exec], options)
+        : spawnSync('sh', ['-c', `command -v ${exec}`], options);
+    const path = result.stdout
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .find(Boolean);
+    if (result.error || result.status !== 0 || !path) {
+        throw new Error([
+            'Visage requires mkcert to configure HTTPS, but mkcert was not found.',
+            '',
+            mkcertInstallInstructions(),
+        ].join('\n'));
+    }
+    return path;
+}
+function mkcertInstallInstructions() {
+    const common = [
+        'After installing mkcert, run `mkcert -install` once when local ' +
+            'certificates should be trusted.',
+        'Install docs: https://github.com/FiloSottile/mkcert#installation',
+        'Set VISAGE_MKCERT=/path/to/mkcert to use a custom executable.',
+    ];
+    const platform = process.platform;
+    if (platform === 'darwin') {
+        return [
+            'Install mkcert with Homebrew:',
+            '  brew install mkcert',
+            '  brew install nss # optional, for Firefox',
+            ...common,
+        ].join('\n');
+    }
+    if (platform === 'win32') {
+        return [
+            'Install mkcert with Chocolatey or Scoop:',
+            '  choco install mkcert',
+            '  scoop install mkcert',
+            ...common,
+        ].join('\n');
+    }
+    if (platform === 'linux') {
+        return [
+            'Install mkcert with your Linux package manager. Common commands:',
+            '  sudo apt install mkcert libnss3-tools',
+            '  sudo dnf install mkcert nss-tools',
+            '  sudo pacman -Syu mkcert nss',
+            ...common,
+        ].join('\n');
+    }
+    return [
+        'Install mkcert for your operating system and make it available on PATH.',
+        ...common,
+    ].join('\n');
 }
 
 let stopRef;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blakearoberts/visage",
-  "version": "0.0.1-rc.26",
+  "version": "0.0.1-rc.27",
   "description": "Vite plugin for local development with HMR and OIDC session cookie lifecycle semantics.",
   "type": "module",
   "author": "Blake Roberts",
@@ -48,14 +48,22 @@
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
     "example": "npm run example:simple",
     "example:simple": "cd examples/simple && npm run dev",
-    "format": "prettier --write \"{docs,examples,src,test}/**/*.{ts,tsx,js,jsx,json,css,html,md}\" \"*.{json,md}\"",
-    "format:check": "prettier --check \"{docs,examples,src,test}/**/*.{ts,tsx,js,jsx,json,css,html,md}\" \"*.{json,md}\"",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
     "promote:codex": "scripts/promote-codex.sh",
     "test": "npm run typecheck && npm run test:unit",
     "test:all": "npm test && npm run test:e2e",
     "test:e2e": "playwright test test/e2e",
     "test:unit": "node --experimental-strip-types --test test/unit/*.test.ts",
-    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json"
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "bcryptjs": "^3.0.3",
+    "eta": "^4.6.0",
+    "yaml": "^2.9.0"
+  },
+  "peerDependencies": {
+    "vite": "^8.0.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.60.0",
@@ -66,10 +74,5 @@
     "tslib": "^2.8.1",
     "typescript": "^6.0.3",
     "vite": "^8.0.13"
-  },
-  "dependencies": {
-    "bcryptjs": "^3.0.3",
-    "eta": "^4.6.0",
-    "yaml": "^2.9.0"
   }
 }