localssl-cli 0.1.3 → 0.1.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sumit Sheokand
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,25 +1,176 @@
-# localssl
+# localssl-cli
 
-One-command local HTTPS for development teams.
+One-command local HTTPS for local development.
 
 ## Install
 
+### One-time run
 ```bash
-npm i -D localssl
-npx localssl
+npx localssl-cli
 ```
 
+### Project install (recommended)
+```bash
+npm i -D localssl-cli
+```
+
+### Global install
+```bash
+npm i -g localssl-cli
+```
+
+> Binary names exposed: `localssl-cli` and `localssl`.
+
+---
+
+## Quick start
+
+```bash
+npx localssl-cli
+```
+
+This does:
+1. Installs/uses mkcert in `~/.localssl`
+2. Creates machine CA and trusts it in OS store
+3. Tries trust import for Firefox + Chrome/Edge NSS stores
+4. Generates project cert/key in `.localssl/`
+5. Configures supported framework HTTPS settings
+6. Updates `.gitignore` to avoid key commits
+7. Syncs team public cert metadata in `localssl.json`
+
+Then run your app as usual (`npm run dev` / `npm start`).
+
+---
+
+## Auto-setup on install
+
+`localssl-cli@0.1.3+` adds setup hooks at install time:
+
+- Adds `predev: "localssl-cli use"` if `dev` exists
+- Adds `prestart: "localssl-cli use"` if `start` exists
+- If `predev`/`prestart` already exists, prepends `localssl-cli use && ...`
+- Skips if already configured
+
+Disable this behavior:
+```bash
+LOCALSSL_SKIP_POSTINSTALL=1 npm i -D localssl-cli
+```
+
+---
+
 ## 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
+### `localssl-cli` (default)
+Runs project setup flow (`use`).
+
+### `localssl-cli init`
+Machine bootstrap only:
+- mkcert setup
+- machine CA install
+- trust stores (OS + Firefox + Chrome/Edge NSS)
+
+### `localssl-cli use [hosts...]`
+Project setup only:
+- detects hosts from `package.json` + `.env`/`.env.local`
+- defaults: `localhost`, `127.0.0.1`, `::1`
+- generates `.localssl/cert.pem` and `.localssl/key.pem`
+- injects framework HTTPS config if supported
+
+Examples:
+```bash
+localssl-cli use
+localssl-cli use myapp.local api.myapp.local
+```
+
+### `localssl-cli use --open` or `localssl-cli --open`
+Same as setup, then opens a guessed HTTPS URL in default browser.
 
-## Team sharing
+### `localssl-cli trust`
+Imports teammate public CAs from `localssl.json` into local trust stores.
 
-`localssl.json` is safe to commit. It stores only public CA certificates.
+### `localssl-cli status`
+Shows:
+- machine CA validity
+- project cert validity
+- detected framework
+- hosts/team summary
+- warning when cert expires in <=30 days
+
+### `localssl-cli renew`
+Regenerates project cert/key (keeps machine CA).
+
+### `localssl-cli qr`
+Starts temporary HTTP server to download CA cert and prints QR code for mobile install.
+
+### `localssl-cli ci`
+CI-only mode (`CI=true`):
+- ephemeral CA/cert generation
+- exports `NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE`, `REQUESTS_CA_BUNDLE`
+- also exports `LOCALSSL_CERT_FILE`, `LOCALSSL_KEY_FILE`
+
+### `localssl-cli remove`
+Best-effort cleanup:
+- removes trust from OS/Firefox/Chrome/Edge NSS
+- deletes `~/.localssl`
+- deletes project `.localssl`
+
+---
+
+## Framework support
+
+- **Vite**: injects HTTPS cert/key in `vite.config.*`
+- **Next.js**: updates `dev` script with `--experimental-https` flags
+- **Create React App**: writes HTTPS vars to `.env.local`
+- **Express**: creates `localssl.js` helper exporting HTTPS options
+- **Webpack Dev Server**: injects `devServer.https`
+- **Generic**: prints manual cert/key usage hint
+
+---
+
+## Team sharing (`localssl.json`)
+
+`localssl.json` is safe to commit.
+
+It stores only:
+- project hosts
+- teammate machine metadata
+- teammate **public** CA certificates
+
+It never stores CA private keys.
+
+---
+
+## Security notes
+
+- Private keys are written to project `.localssl/` and ignored by `.gitignore`
+- Team file validation blocks private-key content in `localssl.json`
+- Never share root CA private key files
+
+## Windows permissions behavior
+
+- localssl-cli first trusts certs in `CurrentUser\\Root` (no admin expected)
+- if needed, it prompts: `Admin access needed for machine-wide trust. Continue? (y/N)`
+- choosing `No` keeps safe mode and skips machine-wide trust
+- rerunning `localssl-cli init` repairs trust if CA already exists
+
+---
+
+## Troubleshooting
+
+### Windows `EPERM` when running `npx` inside this package source folder
+Run from another directory, for example:
+```powershell
+cd $env:TEMP
+npx --yes localssl-cli --help
+```
+
+### Firefox/Chrome/Edge trust skipped
+Install `certutil` (NSS tools), then rerun:
+```bash
+localssl-cli init
+```
+
+### Rebuild certs
+```bash
+localssl-cli renew
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "localssl-cli",
-  "version": "0.1.3",
+  "version": "0.1.6",
   "description": "One-command local HTTPS setup for teams",
   "type": "commonjs",
   "main": "src/index.js",

package/src/bootstrap.js

@@ -80,9 +80,9 @@ async function ensureMkcert() {
   return mkcertPath;
 }
 
-function execMkcert(mkcertPath, args) {
+function execMkcert(mkcertPath, args, extraEnv = {}) {
   return new Promise((resolve, reject) => {
-    execFile(mkcertPath, args, { env: { ...process.env, CAROOT: LOCALSSL_HOME } }, (error, stdout, stderr) => {
+    execFile(mkcertPath, args, { env: { ...process.env, CAROOT: LOCALSSL_HOME, ...extraEnv } }, (error, stdout, stderr) => {
       if (error) {
         reject(new Error(stderr || error.message));
         return;
@@ -99,8 +99,8 @@ async function trustSystem(certPath) {
   }
 
   if (process.platform === 'win32') {
-    await trustWindows(certPath);
-    return 'Windows Root store';
+    const scope = await trustWindows(certPath);
+    return scope;
   }
 
   await trustLinux(certPath);
@@ -138,13 +138,35 @@ async function initMachine({ quiet = false } = {}) {
 
   const hasCA = await fs.pathExists(LOCALSSL_CA_PUBLIC);
   if (hasCA) {
+    let repairSummary = 'already configured';
+    try {
+      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();
+      repairSummary = `${systemResult}; ${nodeResult}; Firefox ${firefoxResult.trusted ? 'ok' : 'skipped'}; Chrome/Edge ${chromiumResult.trusted ? 'ok' : 'skipped'}`;
+    } catch (error) {
+      if (!quiet) {
+        warn(`Trust repair skipped: ${error.message}`);
+      }
+    }
+
     if (!quiet) {
-      step(1, 1, 'Machine CA setup', 'skip', '(already configured)');
+      step(1, 1, 'Machine CA setup', 'skip', `(${repairSummary})`);
     }
     return { mkcertPath, initialized: false };
   }
 
-  await execMkcert(mkcertPath, ['-install']);
+  try {
+    await execMkcert(mkcertPath, ['-install'], { TRUST_STORES: 'system,nss' });
+  } catch (error) {
+    const message = error.message || '';
+    const javaTrustError = /keytool|cacerts|access is denied/i.test(message);
+    if (!javaTrustError) {
+      throw error;
+    }
+    warn('Java trust store update skipped (no admin access). System/browser trust still configured.');
+  }
   const systemResult = await trustSystem(LOCALSSL_CA_PUBLIC);
   const firefoxResult = await trustInFirefox(LOCALSSL_CA_PUBLIC);
   const chromiumResult = await trustInChromium(LOCALSSL_CA_PUBLIC);

package/src/prompt.js

@@ -0,0 +1,22 @@
+const readline = require('readline');
+
+async function askYesNo(question, defaultNo = true) {
+  if (process.env.LOCALSSL_ASSUME_YES === '1') {
+    return true;
+  }
+
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    return !defaultNo;
+  }
+
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      const normalized = String(answer || '').trim().toLowerCase();
+      resolve(normalized === 'y' || normalized === 'yes');
+    });
+  });
+}
+
+module.exports = { askYesNo };

package/src/trust/windows.js

@@ -1,20 +1,57 @@
 const { execFile } = require('child_process');
+const { askYesNo } = require('../prompt');
+
+function run(file, args) {
+  return new Promise((resolve) => {
+    execFile(file, args, { windowsHide: true }, (error) => resolve(!error));
+  });
+}
+
+async function trustCurrentUserWithPowerShell(certPath) {
+  const command = `Import-Certificate -FilePath \"${certPath}\" -CertStoreLocation Cert:\\CurrentUser\\Root | Out-Null`;
+  return run('powershell', ['-NoProfile', '-NonInteractive', '-Command', command]);
+}
+
+async function trustMachineWithElevation(certPath) {
+  const command = `$p = Start-Process certutil -ArgumentList '-addstore','-f','ROOT','${certPath}' -Verb RunAs -Wait -PassThru; if ($p.ExitCode -eq 0) { exit 0 } else { exit 1 }`;
+  return run('powershell', ['-NoProfile', '-NonInteractive', '-Command', command]);
+}
 
 function trustCertificate(certPath) {
-  return new Promise((resolve, reject) => {
-    execFile('certutil', ['-addstore', '-f', 'ROOT', certPath], { windowsHide: true }, (error) => {
-      if (error) {
-        reject(new Error('Admin privileges required to install CA on Windows. Re-run terminal as Administrator.'));
-        return;
-      }
-      resolve();
-    });
+  return new Promise(async (resolve, reject) => {
+    const userViaCertutil = await run('certutil', ['-user', '-addstore', '-f', 'ROOT', certPath]);
+    if (userViaCertutil) {
+      resolve('Windows CurrentUser Root');
+      return;
+    }
+
+    const userViaPowerShell = await trustCurrentUserWithPowerShell(certPath);
+    if (userViaPowerShell) {
+      resolve('Windows CurrentUser Root (PowerShell)');
+      return;
+    }
+
+    const consent = await askYesNo('  Admin access needed for machine-wide trust. Continue? (y/N): ');
+    if (!consent) {
+      resolve('Windows trust skipped (user declined admin prompt)');
+      return;
+    }
+
+    const machineStore = await trustMachineWithElevation(certPath);
+    if (machineStore) {
+      resolve('Windows LocalMachine Root (elevated)');
+      return;
+    }
+
+    reject(new Error('Could not install CA in Windows trust stores. Safe mode preserved (no insecure fallback used).'));
   });
 }
 
 function untrustCertificate(certPath) {
   return new Promise((resolve) => {
-    execFile('certutil', ['-delstore', 'ROOT', certPath], { windowsHide: true }, () => resolve());
+    execFile('certutil', ['-user', '-delstore', 'ROOT', certPath], { windowsHide: true }, () => {
+      execFile('certutil', ['-delstore', 'ROOT', certPath], { windowsHide: true }, () => resolve());
+    });
   });
 }