localssl-cli 0.1.0

package/README.md

@@ -0,0 +1,25 @@
+# localssl
+
+One-command local HTTPS for development teams.
+
+## Install
+
+```bash
+npm i -D localssl
+npx localssl
+```
+
+## Commands
+
+- `localssl` / `localssl use` - initialize + create project cert + configure framework
+- `localssl init` - initialize machine CA and trust stores
+- `localssl status` - check expiry and team sync status
+- `localssl renew` - renew project cert
+- `localssl trust` - import team public CAs from `localssl.json`
+- `localssl qr` - serve CA certificate + print QR for phone install
+- `localssl ci` - ephemeral cert setup for CI (`CI=true`)
+- `localssl remove` - uninstall trust and local files
+
+## Team sharing
+
+`localssl.json` is safe to commit. It stores only public CA certificates.

package/bin/localssl.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+const { Command } = require('commander');
+const { initCommand } = require('../src/init');
+const { useProject } = require('../src/use');
+const { runQrServer } = require('../src/mobile');
+const { runCiSetup } = require('../src/ci');
+const { status } = require('../src/status');
+const { renew } = require('../src/renew');
+const { removeAll } = require('../src/remove');
+const { trustTeam } = require('../src/trust');
+const { isCI, err } = require('../src/utils');
+
+const program = new Command();
+
+program
+  .name('localssl')
+  .description('One-command local HTTPS setup')
+  .version('0.1.0');
+
+program
+  .command('init')
+  .description('Initialize machine CA and trust stores')
+  .action(runGuard(initCommand));
+
+program
+  .command('use')
+  .description('Generate per-project certificate and configure framework')
+  .argument('[hosts...]', 'additional hosts')
+  .action(runGuard(async (hosts) => useProject(hosts || [])));
+
+program
+  .command('status')
+  .description('Show cert status and expiry')
+  .action(runGuard(status));
+
+program
+  .command('renew')
+  .description('Regenerate project certificate')
+  .action(runGuard(renew));
+
+program
+  .command('qr')
+  .description('Start mobile CA QR installer server')
+  .action(runGuard(runQrServer));
+
+program
+  .command('ci')
+  .description('Setup ephemeral HTTPS for CI')
+  .action(runGuard(async () => {
+    if (!isCI()) {
+      throw new Error('CI mode expected CI=true environment variable.');
+    }
+    await runCiSetup();
+  }));
+
+program
+  .command('trust')
+  .description('Trust teammate public CAs from localssl.json')
+  .action(runGuard(trustTeam));
+
+program
+  .command('remove')
+  .description('Uninstall localssl from machine and project')
+  .action(runGuard(removeAll));
+
+program.action(runGuard(async () => {
+  await useProject([]);
+}));
+
+program.parseAsync(process.argv);
+
+function runGuard(fn) {
+  return async (...args) => {
+    try {
+      await fn(...args);
+    } catch (error) {
+      err(error.message || 'localssl failed');
+      process.exitCode = 1;
+    }
+  };
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "localssl-cli",
+  "version": "0.1.0",
+  "description": "One-command local HTTPS setup for teams",
+  "type": "commonjs",
+  "main": "src/index.js",
+  "bin": {
+    "localssl": "bin/localssl.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node bin/localssl.js",
+    "test": "node -e \"console.log('No tests yet')\""
+  },
+  "keywords": [
+    "https",
+    "localhost",
+    "mkcert",
+    "developer-experience"
+  ],
+  "license": "MIT",
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "package.json"
+  ],
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "commander": "^12.1.0",
+    "detect-port": "^2.1.0",
+    "fs-extra": "^11.2.0",
+    "qrcode-terminal": "^0.12.0"
+  }
+}

package/src/bootstrap.js

@@ -0,0 +1,175 @@
+const os = require('os');
+const path = require('path');
+const fs = require('fs-extra');
+const https = require('https');
+const { execFile } = require('child_process');
+const { LOCALSSL_HOME, LOCALSSL_CA_PUBLIC, step, warn } = require('./utils');
+const { trustCertificate: trustMac } = require('./trust/macos');
+const { trustCertificate: trustWindows } = require('./trust/windows');
+const { trustCertificate: trustLinux } = require('./trust/linux');
+const { trustInFirefox } = require('./trust/firefox');
+const { trustInChromium } = require('./trust/chromium');
+
+const MKCERT_VERSION = 'v1.4.4';
+
+function getMkcertBinaryPath() {
+  const ext = process.platform === 'win32' ? '.exe' : '';
+  return path.join(LOCALSSL_HOME, `mkcert${ext}`);
+}
+
+function getMkcertAssetName() {
+  const platform = process.platform;
+  const arch = os.arch();
+
+  if (platform === 'win32') {
+    if (arch === 'x64') return 'mkcert-v1.4.4-windows-amd64.exe';
+    if (arch === 'arm64') return 'mkcert-v1.4.4-windows-arm64.exe';
+  }
+
+  if (platform === 'darwin') {
+    if (arch === 'x64') return 'mkcert-v1.4.4-darwin-amd64';
+    if (arch === 'arm64') return 'mkcert-v1.4.4-darwin-arm64';
+  }
+
+  if (platform === 'linux') {
+    if (arch === 'x64') return 'mkcert-v1.4.4-linux-amd64';
+    if (arch === 'arm64') return 'mkcert-v1.4.4-linux-arm64';
+  }
+
+  throw new Error(`Unsupported platform/arch: ${platform}/${arch}`);
+}
+
+function downloadFile(url, outputPath) {
+  return new Promise((resolve, reject) => {
+    const request = https.get(url, (response) => {
+      if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+        downloadFile(response.headers.location, outputPath).then(resolve).catch(reject);
+        return;
+      }
+
+      if (response.statusCode !== 200) {
+        reject(new Error(`mkcert download failed: ${response.statusCode}`));
+        return;
+      }
+
+      const file = fs.createWriteStream(outputPath, { mode: 0o755 });
+      response.pipe(file);
+      file.on('finish', () => file.close(resolve));
+    });
+
+    request.on('error', reject);
+  });
+}
+
+async function ensureMkcert() {
+  await fs.ensureDir(LOCALSSL_HOME);
+  const mkcertPath = getMkcertBinaryPath();
+
+  if (await fs.pathExists(mkcertPath)) {
+    return mkcertPath;
+  }
+
+  const asset = getMkcertAssetName();
+  const url = `https://github.com/FiloSottile/mkcert/releases/download/${MKCERT_VERSION}/${asset}`;
+  await downloadFile(url, mkcertPath);
+
+  if (process.platform !== 'win32') {
+    await fs.chmod(mkcertPath, 0o755);
+  }
+
+  return mkcertPath;
+}
+
+function execMkcert(mkcertPath, args) {
+  return new Promise((resolve, reject) => {
+    execFile(mkcertPath, args, { env: { ...process.env, CAROOT: LOCALSSL_HOME } }, (error, stdout, stderr) => {
+      if (error) {
+        reject(new Error(stderr || error.message));
+        return;
+      }
+      resolve(stdout);
+    });
+  });
+}
+
+async function trustSystem(certPath) {
+  if (process.platform === 'darwin') {
+    await trustMac(certPath);
+    return 'macOS system store';
+  }
+
+  if (process.platform === 'win32') {
+    await trustWindows(certPath);
+    return 'Windows Root store';
+  }
+
+  await trustLinux(certPath);
+  return 'Linux system store';
+}
+
+async function configureNodeExtraCACerts() {
+  const value = LOCALSSL_CA_PUBLIC;
+
+  if (process.platform === 'win32') {
+    return new Promise((resolve) => {
+      execFile('setx', ['NODE_EXTRA_CA_CERTS', value], { windowsHide: true }, () => resolve('setx NODE_EXTRA_CA_CERTS')); 
+    });
+  }
+
+  const shellProfile = process.platform === 'darwin' ? path.join(os.homedir(), '.zprofile') : path.join(os.homedir(), '.profile');
+  const exportLine = `export NODE_EXTRA_CA_CERTS=\"${value}\"`;
+
+  let current = '';
+  if (await fs.pathExists(shellProfile)) {
+    current = await fs.readFile(shellProfile, 'utf8');
+  }
+
+  if (!current.includes('NODE_EXTRA_CA_CERTS')) {
+    await fs.appendFile(shellProfile, `\n${exportLine}\n`);
+    return `updated ${path.basename(shellProfile)}`;
+  }
+
+  return `${path.basename(shellProfile)} already configured`;
+}
+
+async function initMachine({ quiet = false } = {}) {
+  await fs.ensureDir(LOCALSSL_HOME);
+  const mkcertPath = await ensureMkcert();
+
+  const hasCA = await fs.pathExists(LOCALSSL_CA_PUBLIC);
+  if (hasCA) {
+    if (!quiet) {
+      step(1, 1, 'Machine CA setup', 'skip', '(already configured)');
+    }
+    return { mkcertPath, initialized: false };
+  }
+
+  await execMkcert(mkcertPath, ['-install']);
+  const systemResult = await trustSystem(LOCALSSL_CA_PUBLIC);
+  const firefoxResult = await trustInFirefox(LOCALSSL_CA_PUBLIC);
+  const chromiumResult = await trustInChromium(LOCALSSL_CA_PUBLIC);
+  const nodeResult = await configureNodeExtraCACerts();
+
+  if (!quiet) {
+    const firefoxText = firefoxResult.trusted ? `+ Firefox (${firefoxResult.reason})` : `+ Firefox skipped (${firefoxResult.reason})`;
+    const chromiumText = chromiumResult.trusted ? `+ Chrome/Edge (${chromiumResult.reason})` : `+ Chrome/Edge skipped (${chromiumResult.reason})`;
+    step(1, 1, 'Installing local CA', 'ok', `(${systemResult} ${firefoxText} ${chromiumText}; ${nodeResult})`);
+  }
+
+  if (!firefoxResult.trusted) {
+    warn(`Firefox trust skipped: ${firefoxResult.reason}`);
+  }
+
+  if (!chromiumResult.trusted) {
+    warn(`Chrome/Edge NSS trust skipped: ${chromiumResult.reason}`);
+  }
+
+  return { mkcertPath, initialized: true };
+}
+
+module.exports = {
+  initMachine,
+  ensureMkcert,
+  execMkcert,
+  getMkcertBinaryPath
+};

package/src/certgen.js

@@ -0,0 +1,66 @@
+const path = require('path');
+const fs = require('fs-extra');
+const { PROJECT_DIR, PROJECT_LOCALSSL_DIR, PROJECT_CERT, PROJECT_KEY } = require('./utils');
+const { execMkcert } = require('./bootstrap');
+
+function parseHostsFromUrl(value) {
+  try {
+    const normalized = value.startsWith('http') ? value : `https://${value}`;
+    const host = new URL(normalized).hostname;
+    return host ? [host] : [];
+  } catch {
+    return [];
+  }
+}
+
+async function detectHostsFromProject() {
+  const hosts = new Set(['localhost', '127.0.0.1', '::1']);
+
+  const packageJsonPath = path.join(PROJECT_DIR, 'package.json');
+  if (await fs.pathExists(packageJsonPath)) {
+    const pkg = await fs.readJson(packageJsonPath).catch(() => ({}));
+    if (typeof pkg.proxy === 'string') {
+      parseHostsFromUrl(pkg.proxy).forEach((host) => hosts.add(host));
+    }
+  }
+
+  for (const file of ['.env', '.env.local']) {
+    const envPath = path.join(PROJECT_DIR, file);
+    if (!(await fs.pathExists(envPath))) {
+      continue;
+    }
+
+    const content = await fs.readFile(envPath, 'utf8');
+    const lines = content.split(/\r?\n/);
+    for (const line of lines) {
+      const [key, raw] = line.split('=');
+      if (!key || !raw) {
+        continue;
+      }
+
+      const value = raw.trim().replace(/^['"]|['"]$/g, '');
+      if (/VITE_DEV_SERVER_HOST|NEXT_PUBLIC_URL|APP_URL|HOST|DEV_URL/i.test(key)) {
+        parseHostsFromUrl(value).forEach((host) => hosts.add(host));
+      }
+    }
+  }
+
+  return [...hosts];
+}
+
+async function generateProjectCert({ mkcertPath, hosts, force = false }) {
+  await fs.ensureDir(PROJECT_LOCALSSL_DIR);
+
+  const certExists = (await fs.pathExists(PROJECT_CERT)) && (await fs.pathExists(PROJECT_KEY));
+  if (certExists && !force) {
+    return { generated: false, certPath: PROJECT_CERT, keyPath: PROJECT_KEY };
+  }
+
+  await execMkcert(mkcertPath, ['-cert-file', PROJECT_CERT, '-key-file', PROJECT_KEY, ...hosts]);
+  return { generated: true, certPath: PROJECT_CERT, keyPath: PROJECT_KEY };
+}
+
+module.exports = {
+  detectHostsFromProject,
+  generateProjectCert
+};

package/src/ci.js

@@ -0,0 +1,51 @@
+const os = require('os');
+const path = require('path');
+const fs = require('fs-extra');
+const { execFile } = require('child_process');
+const { ensureMkcert } = require('./bootstrap');
+
+function execWithEnv(file, args, env) {
+  return new Promise((resolve, reject) => {
+    execFile(file, args, { env }, (error, stdout, stderr) => {
+      if (error) {
+        reject(new Error(stderr || error.message));
+        return;
+      }
+      resolve(stdout);
+    });
+  });
+}
+
+async function runCiSetup() {
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'localssl-'));
+  const certDir = path.join(tempRoot, 'certs');
+  const cert = path.join(certDir, 'cert.pem');
+  const key = path.join(certDir, 'key.pem');
+  const ca = path.join(tempRoot, 'rootCA.pem');
+  await fs.ensureDir(certDir);
+
+  const mkcertPath = await ensureMkcert();
+  const env = { ...process.env, CAROOT: tempRoot };
+  await execWithEnv(mkcertPath, ['-install'], env);
+  await execWithEnv(mkcertPath, ['-cert-file', cert, '-key-file', key, 'localhost', '127.0.0.1', '::1'], env);
+
+  const vars = {
+    NODE_EXTRA_CA_CERTS: ca,
+    SSL_CERT_FILE: ca,
+    REQUESTS_CA_BUNDLE: ca,
+    LOCALSSL_CERT_FILE: cert,
+    LOCALSSL_KEY_FILE: key
+  };
+
+  if (process.env.GITHUB_ENV) {
+    const lines = Object.entries(vars).map(([k, v]) => `${k}=${v}`).join('\n') + '\n';
+    await fs.appendFile(process.env.GITHUB_ENV, lines);
+  }
+
+  console.log('  CI HTTPS ready ✓');
+  for (const [k, v] of Object.entries(vars)) {
+    console.log(`  export ${k}=${v}`);
+  }
+}
+
+module.exports = { runCiSetup };

package/src/frameworks/cra.js

@@ -0,0 +1,42 @@
+const path = require('path');
+const fs = require('fs-extra');
+const { PROJECT_DIR } = require('../utils');
+
+async function configureCra(certPath, keyPath) {
+  const envLocalPath = path.join(PROJECT_DIR, '.env.local');
+  const vars = {
+    HTTPS: 'true',
+    SSL_CRT_FILE: certPath,
+    SSL_KEY_FILE: keyPath
+  };
+
+  let current = '';
+  if (await fs.pathExists(envLocalPath)) {
+    current = await fs.readFile(envLocalPath, 'utf8');
+  }
+
+  let changed = false;
+  let updated = current;
+  for (const [key, value] of Object.entries(vars)) {
+    const line = `${key}=${value}`;
+    const regex = new RegExp(`^${key}=.*$`, 'm');
+    if (regex.test(updated)) {
+      if (!updated.includes(line)) {
+        updated = updated.replace(regex, line);
+        changed = true;
+      }
+    } else {
+      updated += `${updated.endsWith('\n') || !updated ? '' : '\n'}${line}\n`;
+      changed = true;
+    }
+  }
+
+  if (!changed) {
+    return { updated: false, details: 'already configured' };
+  }
+
+  await fs.writeFile(envLocalPath, updated);
+  return { updated: true, details: '.env.local updated' };
+}
+
+module.exports = { configureCra };

package/src/frameworks/detect.js

@@ -0,0 +1,23 @@
+const path = require('path');
+const fs = require('fs-extra');
+const { PROJECT_DIR } = require('../utils');
+
+async function detectFramework() {
+  const packageJsonPath = path.join(PROJECT_DIR, 'package.json');
+  if (!(await fs.pathExists(packageJsonPath))) {
+    return 'generic';
+  }
+
+  const pkg = await fs.readJson(packageJsonPath).catch(() => ({}));
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+  if (deps.vite) return 'vite';
+  if (deps.next) return 'nextjs';
+  if (deps['react-scripts']) return 'cra';
+  if (deps.express) return 'express';
+  if (deps['webpack-dev-server']) return 'webpack';
+
+  return 'generic';
+}
+
+module.exports = { detectFramework };

package/src/frameworks/express.js

@@ -0,0 +1,17 @@
+const path = require('path');
+const fs = require('fs-extra');
+const { PROJECT_DIR } = require('../utils');
+
+async function configureExpress(certPath, keyPath) {
+  const helperPath = path.join(PROJECT_DIR, 'localssl.js');
+  if (await fs.pathExists(helperPath)) {
+    return { updated: false, details: 'localssl.js already exists' };
+  }
+
+  const content = `const fs = require('fs');\n\nconst httpsOptions = {\n  cert: fs.readFileSync('${certPath.replace(/\\/g, '/')}'),\n  key: fs.readFileSync('${keyPath.replace(/\\/g, '/')}')\n};\n\nmodule.exports = { httpsOptions };\n`;
+
+  await fs.writeFile(helperPath, content);
+  return { updated: true, details: 'localssl.js created' };
+}
+
+module.exports = { configureExpress };

package/src/frameworks/index.js

@@ -0,0 +1,43 @@
+const { detectFramework } = require('./detect');
+const { configureVite } = require('./vite');
+const { configureNext } = require('./nextjs');
+const { configureCra } = require('./cra');
+const { configureExpress } = require('./express');
+const { configureWebpack } = require('./webpack');
+
+async function configureFramework(certPath, keyPath) {
+  const framework = await detectFramework();
+
+  if (framework === 'vite') {
+    const result = await configureVite(certPath, keyPath);
+    return { framework: 'Vite', ...result };
+  }
+
+  if (framework === 'nextjs') {
+    const result = await configureNext(certPath, keyPath);
+    return { framework: 'Next.js', ...result };
+  }
+
+  if (framework === 'cra') {
+    const result = await configureCra(certPath, keyPath);
+    return { framework: 'Create React App', ...result };
+  }
+
+  if (framework === 'express') {
+    const result = await configureExpress(certPath, keyPath);
+    return { framework: 'Express', ...result };
+  }
+
+  if (framework === 'webpack') {
+    const result = await configureWebpack(certPath, keyPath);
+    return { framework: 'Webpack Dev Server', ...result };
+  }
+
+  return {
+    framework: 'Generic',
+    updated: false,
+    details: `Use cert: ${certPath} and key: ${keyPath}`
+  };
+}
+
+module.exports = { configureFramework };

package/src/frameworks/nextjs.js

@@ -0,0 +1,35 @@
+const path = require('path');
+const fs = require('fs-extra');
+const { PROJECT_DIR } = require('../utils');
+
+function ensureHttpsFlag(script, certPath, keyPath) {
+  if (!script || script.includes('--experimental-https')) {
+    return script;
+  }
+
+  const cert = certPath.replace(/\\/g, '/');
+  const key = keyPath.replace(/\\/g, '/');
+  return `${script} --experimental-https --experimental-https-key ${key} --experimental-https-cert ${cert}`;
+}
+
+async function configureNext(certPath, keyPath) {
+  const packageJsonPath = path.join(PROJECT_DIR, 'package.json');
+  if (!(await fs.pathExists(packageJsonPath))) {
+    return { updated: false, details: 'package.json not found' };
+  }
+
+  const pkg = await fs.readJson(packageJsonPath);
+  pkg.scripts = pkg.scripts || {};
+  const before = pkg.scripts.dev || 'next dev';
+  const nextScript = ensureHttpsFlag(before, certPath, keyPath);
+
+  if (nextScript === before) {
+    return { updated: false, details: 'already configured' };
+  }
+
+  pkg.scripts.dev = nextScript;
+  await fs.writeJson(packageJsonPath, pkg, { spaces: 2 });
+  return { updated: true, details: 'package.json scripts updated' };
+}
+
+module.exports = { configureNext };

package/src/frameworks/vite.js

@@ -0,0 +1,30 @@
+const path = require('path');
+const fs = require('fs-extra');
+const { PROJECT_DIR } = require('../utils');
+
+async function configureVite(certPath, keyPath) {
+  const tsPath = path.join(PROJECT_DIR, 'vite.config.ts');
+  const jsPath = path.join(PROJECT_DIR, 'vite.config.js');
+  const configPath = (await fs.pathExists(tsPath)) ? tsPath : jsPath;
+
+  if (!configPath || !(await fs.pathExists(configPath))) {
+    const content = `import { defineConfig } from 'vite';\nimport fs from 'fs';\n\nexport default defineConfig({\n  server: {\n    https: {\n      cert: fs.readFileSync('${certPath.replace(/\\/g, '/')}'),\n      key: fs.readFileSync('${keyPath.replace(/\\/g, '/')}')\n    }\n  }\n});\n`;
+    await fs.writeFile(tsPath, content);
+    return { updated: true, details: 'vite.config.ts created' };
+  }
+
+  const existing = await fs.readFile(configPath, 'utf8');
+  if (/server\s*:\s*{[\s\S]*https\s*:/m.test(existing) || /https\s*:\s*true/m.test(existing)) {
+    return { updated: false, details: 'already configured' };
+  }
+
+  const injection = `\n\n// localssl\nimport fs from 'fs';\n\nconst localsslHttps = {\n  cert: fs.readFileSync('${certPath.replace(/\\/g, '/')}'),\n  key: fs.readFileSync('${keyPath.replace(/\\/g, '/')}')\n};\n`;
+
+  const updated = existing.replace(/defineConfig\s*\(\s*{/, `defineConfig({\n  server: { https: localsslHttps },`);
+  const finalText = updated === existing ? `${existing}${injection}` : `${injection}${updated}`;
+  await fs.writeFile(configPath, finalText);
+
+  return { updated: true, details: path.basename(configPath) + ' updated' };
+}
+
+module.exports = { configureVite };

package/src/frameworks/webpack.js

@@ -0,0 +1,30 @@
+const path = require('path');
+const fs = require('fs-extra');
+const { PROJECT_DIR } = require('../utils');
+
+async function configureWebpack(certPath, keyPath) {
+  const configPath = path.join(PROJECT_DIR, 'webpack.config.js');
+  if (!(await fs.pathExists(configPath))) {
+    return { updated: false, details: 'webpack.config.js not found' };
+  }
+
+  const existing = await fs.readFile(configPath, 'utf8');
+  if (/devServer\s*:\s*{[\s\S]*https\s*:/m.test(existing)) {
+    return { updated: false, details: 'already configured' };
+  }
+
+  const injection = `\nconst fs = require('fs');\n`;
+  const httpsBlock = `https: { cert: fs.readFileSync('${certPath.replace(/\\/g, '/')}'), key: fs.readFileSync('${keyPath.replace(/\\/g, '/')}') },`;
+
+  let updated = existing;
+  if (!updated.includes("const fs = require('fs');")) {
+    updated = `${injection}${updated}`;
+  }
+
+  updated = updated.replace(/devServer\s*:\s*{/, `devServer: {\n    ${httpsBlock}`);
+  await fs.writeFile(configPath, updated);
+
+  return { updated: true, details: 'webpack.config.js updated' };
+}
+
+module.exports = { configureWebpack };