cloudflare-tunnel-kit 0.1.4 → 0.1.5

package/README.md

@@ -2,9 +2,11 @@
 
 An open-source toolkit for creating and integrating Cloudflare Tunnels through two simple interfaces: a command-line wizard and a local live UI. It replaces scattered shell scripts and Makefile targets with a validated, reviewable, and confirmation-based workflow.
 
+![Demo](images/demo.png)
+
 ## Current version
 
-`0.1.0` is the current MVP and includes:
+`0.1.5` is the current MVP and includes:
 
 - A reusable TypeScript API for validation, plan generation, execution, and redaction.
 - The `cf-tunnel` CLI with `init`, `create`, `quick`, `start`, `stop`, `status`, `doctor`, and `ui` commands.
@@ -41,6 +43,21 @@ Install the package in the project that needs a tunnel:
 npm install --save-dev cloudflare-tunnel-kit
 ```
 
+For a machine-wide command available from any directory, install it globally:
+
+```bash
+npm install --global cloudflare-tunnel-kit
+```
+
+Then use either command name:
+
+```bash
+cf-tunnel doctor
+cftunnel ui
+```
+
+Both commands use the same local application data directory and can be run from any project folder. The global install provides the CLI; `cloudflared` is still a separate prerequisite.
+
 The package exposes the `cf-tunnel` binary locally. Run it through `npx` so no global installation is required:
 
 ```bash

package/dist/app/service.js

@@ -1,5 +1,5 @@
 import crypto from 'node:crypto';
-import { existsSync } from 'node:fs';
+import { existsSync, realpathSync, statSync } from 'node:fs';
 import { resolveAppPaths } from './paths.js';
 import { openStateDatabase } from '../persistence/database.js';
 import { StateStore } from '../persistence/store.js';
@@ -71,8 +71,23 @@ export class TunnelKitService {
         await this.stop(projectId);
     }
     catch { } return this.start(projectId); }
-    async relinkProject(projectId, nextPath) { if (!nextPath?.trim())
-        throw new Error('A new project folder is required.'); this.store.relinkProject(projectId, nextPath); }
+    async relinkProject(projectId, nextPath) {
+        if (!nextPath?.trim())
+            throw new Error('A new project folder is required.');
+        let resolved;
+        try {
+            resolved = realpathSync(nextPath);
+        }
+        catch {
+            throw new Error('The new project path must be an existing project directory.');
+        }
+        if (!statSync(resolved).isDirectory())
+            throw new Error('The new project path must be an existing project directory.');
+        const duplicate = this.store.listProjects().find((project) => project.path === resolved && project.id !== projectId);
+        if (duplicate)
+            throw new Error('Another local project already uses this folder.');
+        this.store.relinkProject(projectId, resolved);
+    }
     async removeLocal(projectId) {
         let session;
         try {

package/dist/core/named-workflow.js

@@ -90,6 +90,11 @@ export class NamedTunnelWorkflow {
         }
         if (!tunnel.uuid || !tunnel.credentialsPath || !tunnel.configPath)
             throw new Error('Saved tunnel identity is incomplete.');
+        if (tunnel.hostname !== input.hostname || tunnel.localUrl !== input.localUrl || tunnel.name !== input.tunnelName) {
+            tunnel = this.store.saveTunnel({ ...tunnel, hostname: input.hostname, localUrl: input.localUrl, name: input.tunnelName });
+            if (!tunnel.uuid || !tunnel.credentialsPath || !tunnel.configPath)
+                throw new Error('Saved tunnel identity is incomplete.');
+        }
         try {
             const credentialStat = await stat(tunnel.credentialsPath);
             if (!credentialStat.isFile())

package/dist/core/redact.js

@@ -2,7 +2,11 @@ const secretKey = /(token|secret|password|private|credential|key|cert)/i;
 export function redact(value, key) {
     if (key && secretKey.test(key))
         return '[REDACTED]';
-    return value.replace(/(Bearer\s+)[^\s]+/gi, '$1[REDACTED]').replace(/([A-Za-z0-9_-]{24,})/g, '[REDACTED]');
+    return value
+        .replace(/-----BEGIN [^-]+-----[\s\S]*?-----END [^-]+-----/gi, '[REDACTED PEM]')
+        .replace(/(Bearer\s+)[^\s]+/gi, '$1[REDACTED]')
+        .replace(/([?&](?:token|secret|password|api[_-]?key|signature|credential)=)[^&\s]+/gi, '$1[REDACTED]')
+        .replace(/([A-Za-z0-9_-]{24,})/g, '[REDACTED]');
 }
 export function redactValue(value, key) {
     if (key && secretKey.test(key))

package/dist/core/types.d.ts

@@ -33,6 +33,8 @@ export interface TunnelConfig {
     tunnelName?: string;
     hostname?: string;
     configPath?: string;
+    allowPublicOrigin?: boolean;
+    allowPrivateNetwork?: boolean;
     laravel?: {
         mapAppUrl?: boolean;
         mapAssetUrl?: boolean;

package/dist/core/validation.js

@@ -2,6 +2,17 @@ import path from 'node:path';
 import { realpathSync } from 'node:fs';
 import { domainToASCII } from 'node:url';
 function issue(code, reason, fix, field) { return { code, reason, fix, field }; }
+function safeOrigin(url, input) {
+    if (url.username || url.password)
+        return issue('INPUT_UNSAFE_ORIGIN', 'localUrl must not contain username or password information.', 'Remove credentials from the URL and configure authentication in the local application.', 'localUrl');
+    const hostname = url.hostname.toLowerCase();
+    const loopback = hostname === 'localhost' || hostname === '::1' || hostname === '127.0.0.1' || hostname.startsWith('127.');
+    if (loopback)
+        return undefined;
+    if (input.allowPrivateNetwork || input.allowPublicOrigin)
+        return undefined;
+    return issue('INPUT_UNSAFE_ORIGIN', 'Only loopback origins are allowed by default.', 'Use localhost or 127.0.0.1, or explicitly enable the reviewed advanced network option.', 'localUrl');
+}
 function inside(root, candidate) {
     try {
         const r = realpathSync(root);
@@ -18,7 +29,10 @@ export function validateTunnelConfig(input) {
     try {
         url = new URL(input.localUrl);
         if (!['http:', 'https:'].includes(url.protocol))
-            throw new Error();
+            throw new Error('invalid protocol');
+        const unsafe = safeOrigin(url, input);
+        if (unsafe)
+            issues.push(unsafe);
     }
     catch {
         issues.push(issue('INPUT_INVALID_URL', 'localUrl must be an http or https URL.', 'Use a value such as http://127.0.0.1:8000.', 'localUrl'));

package/dist/providers/process-supervisor.js

@@ -72,6 +72,15 @@ export class ProcessSupervisor {
         });
         if (stopped)
             session.state = 'stopped';
-        return { stopped, forceRequired: !stopped };
+        if (stopped)
+            return { stopped: true, forceRequired: false };
+        session.child.kill('SIGKILL');
+        const forceStopped = await new Promise(resolve => {
+            const timer = setTimeout(() => resolve(false), graceMs);
+            session.child.once('close', () => { clearTimeout(timer); resolve(true); });
+        });
+        if (forceStopped)
+            session.state = 'stopped';
+        return { stopped: forceStopped, forceRequired: true };
     }
 }

package/dist/ui/server.js

@@ -37,6 +37,8 @@ export function createServer(options = {}) {
             catch (error) {
                 return json(res, { error: error instanceof Error ? error.message : 'Invalid JSON request.' }, error?.code === 'BODY_TOO_LARGE' ? 413 : 400);
             }
+            if (!body || typeof body !== 'object' || Array.isArray(body) || containsCredentialField(body))
+                return json(res, { error: 'Requests must be objects and must not contain secret or credential fields.' }, 400);
             if (url.pathname === '/api/plans/quick')
                 return handle(res, () => service.prepareQuick(body));
             if (url.pathname === '/api/plans/named')
@@ -46,6 +48,9 @@ export function createServer(options = {}) {
             const action = url.pathname.match(/^\/api\/projects\/([^/]+)\/(start|stop|retry|restart)$/);
             if (action)
                 return handle(res, () => service[action[2]](action[1]));
+            const management = url.pathname.match(/^\/api\/projects\/([^/]+)\/(relink|remove-local)$/);
+            if (management)
+                return handle(res, () => management[2] === 'relink' ? service.relinkProject(management[1], body.path) : service.removeLocal(management[1]));
             if (url.pathname === '/api/plan') {
                 const config = body.config ?? {};
                 return handle(res, async () => ({ plan: config.operation === 'quick' ? await service.prepareQuick({ projectPath: config.projectRoot ?? process.cwd(), ...config }) : await service.prepareNamed({ projectPath: config.projectRoot ?? process.cwd(), ...config }) }));
@@ -54,12 +59,19 @@ export function createServer(options = {}) {
         return json(res, { error: 'Not found.' }, 404);
     });
 }
+function containsCredentialField(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    if (Array.isArray(value))
+        return value.some(containsCredentialField);
+    return Object.entries(value).some(([key, nested]) => /(secret|token|password|credential|private[_-]?key|cert)/i.test(key) || containsCredentialField(nested));
+}
 function validMutationRequest(req, token) {
     const received = String(req.headers['x-confirmation-token'] ?? '');
     if (received.length !== token.length || !crypto.timingSafeEqual(Buffer.from(received), Buffer.from(token)))
         return false;
     const host = String(req.headers.host ?? '');
-    if (host && !/^(127\.0\.0\.1|localhost)(:\d+)?$/i.test(host))
+    if (!/^(127\.0\.0\.1|localhost)(:\d+)?$/i.test(host))
         return false;
     const origin = String(req.headers.origin ?? '');
     return !origin || /^http:\/\/(127\.0\.0\.1|localhost)(:\d+)?$/i.test(origin);
@@ -77,6 +89,6 @@ async function handle(res, operation) { try {
 catch (error) {
     return json(res, { error: error instanceof Error ? error.message : String(error) }, 400);
 } }
-function secureHeaders(res) { res.setHeader('X-Content-Type-Options', 'nosniff'); res.setHeader('Content-Security-Policy', "default-src 'self'; style-src 'unsafe-inline'; script-src 'unsafe-inline'; connect-src 'self'; frame-ancestors 'none'"); res.setHeader('Referrer-Policy', 'no-referrer'); res.setHeader('Cache-Control', 'no-store'); }
+function secureHeaders(res) { res.setHeader('X-Content-Type-Options', 'nosniff'); res.setHeader('Content-Security-Policy', "default-src 'self'; style-src 'unsafe-inline'; script-src 'unsafe-inline'; connect-src 'self'; frame-ancestors 'none'"); res.setHeader('X-Frame-Options', 'DENY'); res.setHeader('Permissions-Policy', 'camera=(), microphone=(), geolocation=()'); res.setHeader('Referrer-Policy', 'no-referrer'); res.setHeader('Cache-Control', 'no-store'); }
 function html(res, value) { res.statusCode = 200; res.setHeader('Content-Type', 'text/html; charset=utf-8'); res.end(value); }
 function json(res, value, status = 200) { res.statusCode = status; res.setHeader('Content-Type', 'application/json; charset=utf-8'); res.end(JSON.stringify(value)); }

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "cloudflare-tunnel-kit",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Safe, reusable Cloudflare Tunnel setup for custom and Laravel projects.",
   "type": "module",
   "bin": {
-    "cf-tunnel": "dist/cli/main.js"
+    "cf-tunnel": "dist/cli/main.js",
+    "cftunnel": "dist/cli/main.js"
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -21,7 +22,8 @@
   ],
   "scripts": {
     "build": "tsc",
-    "test": "npm run build && node --test tests/**/*.test.js",
+    "test": "npm run build && npm run test:unit",
+    "test:unit": "node --test --test-timeout=10000 tests/**/*.test.js",
     "dev": "tsc --watch"
   },
   "devDependencies": {