localssl-cli 0.1.2 → 0.1.4

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,169 @@
-# 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
+```
 
-## Team sharing
+### `localssl-cli use --open` or `localssl-cli --open`
+Same as setup, then opens a guessed HTTPS URL in default browser.
 
-`localssl.json` is safe to commit. It stores only public CA certificates.
+### `localssl-cli trust`
+Imports teammate public CAs from `localssl.json` into local trust stores.
+
+### `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
+
+---
+
+## 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.2",
+  "version": "0.1.4",
   "description": "One-command local HTTPS setup for teams",
   "type": "commonjs",
   "main": "src/index.js",
@@ -13,7 +13,8 @@
   },
   "scripts": {
     "start": "node bin/localssl.js",
-    "test": "node -e \"console.log('No tests yet')\""
+    "test": "node -e \"console.log('No tests yet')\"",
+    "postinstall": "node src/postinstall.js"
   },
   "keywords": [
     "https",

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;
@@ -144,7 +144,16 @@ async function initMachine({ quiet = false } = {}) {
     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/postinstall.js

@@ -0,0 +1,60 @@
+const path = require('path');
+const fs = require('fs-extra');
+
+function ensureHook(scripts, hookName, targetCommand, baseScriptName) {
+  if (!scripts[baseScriptName]) {
+    return false;
+  }
+
+  const current = scripts[hookName];
+  if (!current) {
+    scripts[hookName] = targetCommand;
+    return true;
+  }
+
+  if (current.includes('localssl-cli use') || current.includes('localssl use')) {
+    return false;
+  }
+
+  scripts[hookName] = `${targetCommand} && ${current}`;
+  return true;
+}
+
+async function run() {
+  if (process.env.LOCALSSL_SKIP_POSTINSTALL === '1') {
+    return;
+  }
+
+  const packageRoot = path.resolve(__dirname, '..');
+  const initCwd = path.resolve(process.env.INIT_CWD || process.cwd());
+  if (initCwd === packageRoot) {
+    return;
+  }
+
+  const targetPackageJsonPath = path.join(initCwd, 'package.json');
+  if (!(await fs.pathExists(targetPackageJsonPath))) {
+    return;
+  }
+
+  let targetPackage;
+  try {
+    targetPackage = await fs.readJson(targetPackageJsonPath);
+  } catch {
+    return;
+  }
+
+  targetPackage.scripts = targetPackage.scripts || {};
+
+  let changed = false;
+  changed = ensureHook(targetPackage.scripts, 'predev', 'localssl-cli use', 'dev') || changed;
+  changed = ensureHook(targetPackage.scripts, 'prestart', 'localssl-cli use', 'start') || changed;
+
+  if (!changed) {
+    return;
+  }
+
+  await fs.writeJson(targetPackageJsonPath, targetPackage, { spaces: 2 });
+  console.log('localssl-cli: added predev/prestart HTTPS setup hooks');
+}
+
+run().catch(() => {});