@neuralnomads/codenomad-dev 0.10.3-dev-20260213-ba418a85

package/README.md

@@ -0,0 +1,126 @@
+# CodeNomad Server
+
+**CodeNomad Server** is the high-performance engine behind the CodeNomad cockpit. It transforms your machine into a robust development host, managing the lifecycle of multiple OpenCode instances and providing the low-latency data streams that long-haul builders demand. It bridges your local filesystem with the UI, ensuring that whether you are on localhost or a remote tunnel, you have the speed, clarity, and control of a native workspace.
+
+## Features & Capabilities
+
+### 🌍 Deployment Freedom
+- **Remote Access**: Host CodeNomad on a powerful workstation and access it from your lightweight laptop.
+- **Code Anywhere**: Tunnel in via VPN or SSH to code securely from coffee shops or while traveling.
+- **Multi-Device**: The responsive web client works on tablets and iPads, turning any screen into a dev terminal.
+- **Always-On**: Run as a background service so your sessions are always ready when you connect.
+
+### ⚡️ Workspace Power
+- **Multi-Instance**: Juggle multiple OpenCode sessions side-by-side with per-instance tabs.
+- **Long-Context Native**: Scroll through massive transcripts without hitches.
+- **Deep Task Awareness**: Monitor background tasks and child sessions without losing your flow.
+- **Command Palette**: A single, global palette to jump tabs, launch tools, and fire shortcuts.
+
+## Prerequisites
+- **OpenCode**: `opencode` must be installed and configured on your system.
+- Node.js 18+ and npm (for running or building from source).
+- A workspace folder on disk you want to serve.
+- Optional: a Chromium-based browser if you want `--launch` to open the UI automatically.
+
+## Usage
+
+### Run via npx (Recommended)
+You can run CodeNomad directly without installing it:
+
+```sh
+npx @neuralnomads/codenomad --launch
+```
+
+On startup, CodeNomad prints two URLs:
+
+- `Local Connection URL : ...` (used by desktop shells)
+- `Remote Connection URL : ...` (used by browsers/other machines when remote access is enabled)
+
+### Install Globally
+Or install it globally to use the `codenomad` command:
+
+```sh
+npm install -g @neuralnomads/codenomad
+codenomad --launch
+```
+
+### Common Flags
+You can configure the server using flags or environment variables:
+
+| Flag | Env Variable | Description |
+|------|--------------|-------------|
+| `--https <enabled>` | `CLI_HTTPS` | Enable HTTPS listener (default `true`) |
+| `--http <enabled>` | `CLI_HTTP` | Enable HTTP listener (default `false`) |
+| `--https-port <number>` | `CLI_HTTPS_PORT` | HTTPS port (default `9898`, use `0` for auto) |
+| `--http-port <number>` | `CLI_HTTP_PORT` | HTTP port (default `9899`, use `0` for auto) |
+| `--tls-key <path>` | `CLI_TLS_KEY` | TLS private key (PEM). Requires `--tls-cert`. |
+| `--tls-cert <path>` | `CLI_TLS_CERT` | TLS certificate (PEM). Requires `--tls-key`. |
+| `--tls-ca <path>` | `CLI_TLS_CA` | Optional CA chain/bundle (PEM) |
+| `--tlsSANs <list>` | `CLI_TLS_SANS` | Additional TLS SANs (comma-separated) |
+| `--host <addr>` | `CLI_HOST` | Interface to bind (default 127.0.0.1) |
+| `--workspace-root <path>` | `CLI_WORKSPACE_ROOT` | Default root for new workspaces |
+| `--unrestricted-root` | `CLI_UNRESTRICTED_ROOT` | Allow full-filesystem browsing |
+| `--config <path>` | `CLI_CONFIG` | Config file location |
+| `--launch` | `CLI_LAUNCH` | Open the UI in a Chromium-based browser |
+| `--log-level <level>` | `CLI_LOG_LEVEL` | Logging level (trace, debug, info, warn, error) |
+| `--username <username>` | `CODENOMAD_SERVER_USERNAME` | Username for CodeNomad's internal auth (default `codenomad`) |
+| `--password <password>` | `CODENOMAD_SERVER_PASSWORD` | Password for CodeNomad's internal auth |
+| `--generate-token` | `CODENOMAD_GENERATE_TOKEN` | Emit a one-time local bootstrap token for desktop flows |
+| `--dangerously-skip-auth` | `CODENOMAD_SKIP_AUTH` | Disable CodeNomad's internal auth (use only behind a trusted perimeter) |
+
+### HTTP vs HTTPS
+
+- Default: `--https=true --http=false` (HTTPS only).
+- To run plain HTTP only (useful for development):
+
+```sh
+codenomad --https=false --http=true
+```
+
+- To run both HTTPS (for remote) and HTTP loopback (for desktop):
+
+```sh
+codenomad --https=true --http=true
+```
+
+### Remote Access Binding Rules
+
+- When remote access is enabled (bind host is non-loopback, e.g. `--host 0.0.0.0`):
+  - HTTP listens on `127.0.0.1` only.
+  - HTTPS listens on `--host` (LAN/all interfaces).
+- When remote access is disabled (bind host is loopback, e.g. `--host 127.0.0.1`):
+  - Both HTTP and HTTPS listen on `127.0.0.1`.
+
+### Self-Signed Certificates
+
+If `--https=true` and you do not provide `--tls-key/--tls-cert`, CodeNomad generates a local certificate automatically under your config directory:
+
+- `~/.config/codenomad/tls/ca-cert.pem`
+- `~/.config/codenomad/tls/server-cert.pem`
+
+Certificates are valid for about 30 days and rotate automatically on startup when needed. You can add extra SANs via:
+
+```sh
+codenomad --tlsSANs "localhost,127.0.0.1,my-hostname,192.168.1.10"
+```
+
+### Authentication
+- Default behavior: CodeNomad requires a login (username/password) and stores a session cookie in the browser.
+- `--dangerously-skip-auth` / `CODENOMAD_SKIP_AUTH=true` disables the login prompt and treats all requests as authenticated.
+  Use this only when access is already protected by another layer (SSO proxy, VPN, Coder workspace auth, etc.).
+  If you bind to `0.0.0.0` while skipping auth, anyone who can reach the port can access the API.
+
+### Progressive Web App (PWA)
+When running as a server CodeNomad can also be installed as a PWA from any supported browser, giving you a native app experience just like the Electron installation but executing on the remote server instead.
+
+1. Open the CodeNomad UI in a Chromium-based browser (Chrome, Edge, Brave, etc.).
+2. Click the install icon in the address bar, or use the browser menu → "Install CodeNomad".
+3. The app will open in a standalone window and appear in your OS app list.
+
+> **TLS requirement**
+> Browsers require a secure (`https://`) connection for PWA installation.
+> If you host CodeNomad on a remote machine, use HTTPS. Self-signed certificates generally won't work unless they are explicitly trusted by the device/browser (e.g., via a custom CA).
+
+### Data Storage
+- **Config**: `~/.config/codenomad/config.json`
+- **Instance Data**: `~/.config/codenomad/instances` (chat history, etc.)

package/dist/api-types.js

@@ -0,0 +1 @@
+export const WINDOWS_DRIVES_ROOT = "__drives__";

package/dist/auth/auth-store.js

@@ -0,0 +1,134 @@
+import fs from "fs";
+import path from "path";
+import { hashPassword, verifyPassword } from "./password-hash";
+export class AuthStore {
+    constructor(authFilePath, logger) {
+        this.authFilePath = authFilePath;
+        this.logger = logger;
+        this.cachedFile = null;
+        this.overrideAuth = null;
+        this.bootstrapUsername = null;
+    }
+    getAuthFilePath() {
+        return this.authFilePath;
+    }
+    load() {
+        if (this.overrideAuth) {
+            return this.overrideAuth;
+        }
+        if (this.cachedFile) {
+            return this.cachedFile;
+        }
+        try {
+            if (!fs.existsSync(this.authFilePath)) {
+                return null;
+            }
+            const raw = fs.readFileSync(this.authFilePath, "utf-8");
+            const parsed = JSON.parse(raw);
+            if (!parsed || parsed.version !== 1) {
+                this.logger.warn({ authFilePath: this.authFilePath }, "Auth file has unsupported version");
+                return null;
+            }
+            this.cachedFile = parsed;
+            return parsed;
+        }
+        catch (error) {
+            this.logger.warn({ err: error, authFilePath: this.authFilePath }, "Failed to load auth file");
+            return null;
+        }
+    }
+    ensureInitialized(params) {
+        const password = params.password?.trim();
+        if (password) {
+            const now = new Date().toISOString();
+            const runtime = {
+                version: 1,
+                username: params.username,
+                password: hashPassword(password),
+                userProvided: true,
+                updatedAt: now,
+            };
+            this.overrideAuth = runtime;
+            this.cachedFile = null;
+            this.bootstrapUsername = null;
+            this.logger.debug({ authFilePath: this.authFilePath }, "Using runtime auth password override; ignoring auth file");
+            return;
+        }
+        const existing = this.load();
+        if (existing) {
+            if (existing.username !== params.username) {
+                // Keep existing username unless explicitly overridden later.
+                this.logger.debug({ existing: existing.username, requested: params.username }, "Auth username differs from requested");
+            }
+            this.bootstrapUsername = null;
+            return;
+        }
+        if (params.allowBootstrapWithoutPassword) {
+            this.bootstrapUsername = params.username;
+            this.logger.debug({ authFilePath: this.authFilePath }, "No auth file present; bootstrap-only mode enabled");
+            return;
+        }
+        throw new Error(`No server password configured. Create ${this.authFilePath} or start with --password / CODENOMAD_SERVER_PASSWORD.`);
+    }
+    validateCredentials(username, password) {
+        const auth = this.load();
+        if (!auth) {
+            return false;
+        }
+        if (username !== auth.username) {
+            return false;
+        }
+        return verifyPassword(password, auth.password);
+    }
+    setPassword(params) {
+        if (this.overrideAuth) {
+            throw new Error("Server password is provided via CLI/env and cannot be changed while running. Restart without --password / CODENOMAD_SERVER_PASSWORD to use auth.json.");
+        }
+        const current = this.load();
+        if (!current) {
+            if (!this.bootstrapUsername) {
+                throw new Error("Auth is not initialized");
+            }
+            const created = {
+                version: 1,
+                username: this.bootstrapUsername,
+                password: hashPassword(params.password),
+                userProvided: params.markUserProvided,
+                updatedAt: new Date().toISOString(),
+            };
+            this.persist(created);
+            this.bootstrapUsername = null;
+            return { username: created.username, passwordUserProvided: created.userProvided };
+        }
+        const next = {
+            ...current,
+            password: hashPassword(params.password),
+            userProvided: params.markUserProvided,
+            updatedAt: new Date().toISOString(),
+        };
+        this.persist(next);
+        return { username: next.username, passwordUserProvided: next.userProvided };
+    }
+    getStatus() {
+        const current = this.load();
+        if (current) {
+            return { username: current.username, passwordUserProvided: current.userProvided };
+        }
+        if (this.bootstrapUsername) {
+            return { username: this.bootstrapUsername, passwordUserProvided: false };
+        }
+        throw new Error("Auth is not initialized");
+    }
+    persist(auth) {
+        try {
+            fs.mkdirSync(path.dirname(this.authFilePath), { recursive: true });
+            fs.writeFileSync(this.authFilePath, JSON.stringify(auth, null, 2), "utf-8");
+            this.cachedFile = auth;
+            this.logger.debug({ authFilePath: this.authFilePath }, "Persisted auth file");
+        }
+        catch (error) {
+            this.logger.error({ err: error, authFilePath: this.authFilePath }, "Failed to persist auth file");
+            throw error;
+        }
+    }
+}

package/dist/auth/http-auth.js

@@ -0,0 +1,37 @@
+export function parseCookies(header) {
+    const result = {};
+    if (!header)
+        return result;
+    const parts = header.split(";");
+    for (const part of parts) {
+        const index = part.indexOf("=");
+        if (index < 0)
+            continue;
+        const key = part.slice(0, index).trim();
+        const value = part.slice(index + 1).trim();
+        if (!key)
+            continue;
+        result[key] = decodeURIComponent(value);
+    }
+    return result;
+}
+export function isLoopbackAddress(remoteAddress) {
+    if (!remoteAddress)
+        return false;
+    if (remoteAddress === "127.0.0.1" || remoteAddress === "::1")
+        return true;
+    if (remoteAddress === "::ffff:127.0.0.1")
+        return true;
+    return false;
+}
+export function wantsHtml(request) {
+    const accept = (request.headers["accept"] ?? "").toString().toLowerCase();
+    return accept.includes("text/html") || accept.includes("application/xhtml");
+}
+export function sendUnauthorized(request, reply) {
+    if (request.method === "GET" && !request.url.startsWith("/api/") && wantsHtml(request)) {
+        reply.redirect("/login");
+        return;
+    }
+    reply.code(401).send({ error: "Unauthorized" });
+}

package/dist/auth/manager.js

@@ -0,0 +1,128 @@
+import path from "path";
+import { AuthStore } from "./auth-store";
+import { TokenManager } from "./token-manager";
+import { SessionManager } from "./session-manager";
+import { isLoopbackAddress, parseCookies } from "./http-auth";
+export const BOOTSTRAP_TOKEN_STDOUT_PREFIX = "CODENOMAD_BOOTSTRAP_TOKEN:";
+export const DEFAULT_AUTH_USERNAME = "codenomad";
+export const DEFAULT_AUTH_COOKIE_NAME = "codenomad_session";
+export class AuthManager {
+    constructor(init, logger) {
+        this.init = init;
+        this.logger = logger;
+        this.sessionManager = new SessionManager();
+        this.cookieName = DEFAULT_AUTH_COOKIE_NAME;
+        this.authEnabled = !Boolean(init.dangerouslySkipAuth);
+        if (!this.authEnabled) {
+            this.authStore = null;
+            this.tokenManager = null;
+            return;
+        }
+        const authFilePath = resolveAuthFilePath(init.configPath);
+        this.authStore = new AuthStore(authFilePath, logger.child({ component: "auth" }));
+        // Startup: password comes from CLI/env, auth.json, or bootstrap-only mode.
+        this.authStore.ensureInitialized({
+            username: init.username,
+            password: init.password,
+            allowBootstrapWithoutPassword: init.generateToken,
+        });
+        this.tokenManager = init.generateToken ? new TokenManager(60000) : null;
+    }
+    isAuthEnabled() {
+        return this.authEnabled;
+    }
+    getCookieName() {
+        return this.cookieName;
+    }
+    isTokenBootstrapEnabled() {
+        return Boolean(this.tokenManager);
+    }
+    issueBootstrapToken() {
+        if (!this.tokenManager)
+            return null;
+        return this.tokenManager.generate();
+    }
+    consumeBootstrapToken(token) {
+        if (!this.tokenManager)
+            return false;
+        return this.tokenManager.consume(token);
+    }
+    validateLogin(username, password) {
+        if (!this.authEnabled) {
+            return true;
+        }
+        return this.requireAuthStore().validateCredentials(username, password);
+    }
+    createSession(username) {
+        if (!this.authEnabled) {
+            return { id: "auth-disabled", createdAt: Date.now(), username: this.init.username };
+        }
+        return this.sessionManager.createSession(username);
+    }
+    getStatus() {
+        if (!this.authEnabled) {
+            return { username: this.init.username, passwordUserProvided: false };
+        }
+        return this.requireAuthStore().getStatus();
+    }
+    setPassword(password) {
+        if (!this.authEnabled) {
+            throw new Error("Internal authentication is disabled");
+        }
+        return this.requireAuthStore().setPassword({ password, markUserProvided: true });
+    }
+    isLoopbackRequest(request) {
+        return isLoopbackAddress(request.socket.remoteAddress);
+    }
+    getSessionFromRequest(request) {
+        if (!this.authEnabled) {
+            // When auth is disabled, treat all requests as authenticated.
+            // We still return a stable username so callers can display it.
+            return { username: this.init.username, sessionId: "auth-disabled" };
+        }
+        const cookies = parseCookies(request.headers.cookie);
+        const sessionId = cookies[this.cookieName];
+        const session = this.sessionManager.getSession(sessionId);
+        if (!session)
+            return null;
+        return { username: session.username, sessionId: session.id };
+    }
+    setSessionCookie(reply, sessionId) {
+        reply.header("Set-Cookie", buildSessionCookie(this.cookieName, sessionId));
+    }
+    setSessionCookieWithOptions(reply, sessionId, options) {
+        reply.header("Set-Cookie", buildSessionCookie(this.cookieName, sessionId, options));
+    }
+    clearSessionCookie(reply) {
+        reply.header("Set-Cookie", buildSessionCookie(this.cookieName, "", { maxAgeSeconds: 0 }));
+    }
+    clearSessionCookieWithOptions(reply, options) {
+        reply.header("Set-Cookie", buildSessionCookie(this.cookieName, "", { maxAgeSeconds: 0, ...options }));
+    }
+    requireAuthStore() {
+        if (!this.authStore) {
+            throw new Error("Auth store is unavailable");
+        }
+        return this.authStore;
+    }
+}
+function resolveAuthFilePath(configPath) {
+    const resolvedConfigPath = resolvePath(configPath);
+    return path.join(path.dirname(resolvedConfigPath), "auth.json");
+}
+function resolvePath(filePath) {
+    if (filePath.startsWith("~/")) {
+        return path.join(process.env.HOME ?? "", filePath.slice(2));
+    }
+    return path.resolve(filePath);
+}
+function buildSessionCookie(name, value, options) {
+    const parts = [`${name}=${encodeURIComponent(value)}`, "HttpOnly", "Path=/", "SameSite=Lax"];
+    if (options?.secure) {
+        parts.push("Secure");
+    }
+    if (options?.maxAgeSeconds !== undefined) {
+        parts.push(`Max-Age=${Math.max(0, Math.floor(options.maxAgeSeconds))}`);
+    }
+    return parts.join("; ");
+}

package/dist/auth/password-hash.js

@@ -0,0 +1,32 @@
+import crypto from "crypto";
+const DEFAULT_SCRYPT_PARAMS = {
+    N: 16384,
+    r: 8,
+    p: 1,
+    maxmem: 32 * 1024 * 1024,
+};
+export function hashPassword(password) {
+    const salt = crypto.randomBytes(16);
+    const params = DEFAULT_SCRYPT_PARAMS;
+    const keyLength = 64;
+    const derived = crypto.scryptSync(password, salt, keyLength, params);
+    return {
+        algorithm: "scrypt",
+        saltBase64: salt.toString("base64"),
+        hashBase64: Buffer.from(derived).toString("base64"),
+        keyLength,
+        params,
+    };
+}
+export function verifyPassword(password, record) {
+    if (record.algorithm !== "scrypt") {
+        return false;
+    }
+    const salt = Buffer.from(record.saltBase64, "base64");
+    const expected = Buffer.from(record.hashBase64, "base64");
+    const derived = crypto.scryptSync(password, salt, record.keyLength, record.params);
+    if (expected.length !== derived.length) {
+        return false;
+    }
+    return crypto.timingSafeEqual(expected, Buffer.from(derived));
+}

package/dist/auth/session-manager.js

@@ -0,0 +1,17 @@
+import crypto from "crypto";
+export class SessionManager {
+    constructor() {
+        this.sessions = new Map();
+    }
+    createSession(username) {
+        const id = crypto.randomBytes(32).toString("base64url");
+        const info = { id, createdAt: Date.now(), username };
+        this.sessions.set(id, info);
+        return info;
+    }
+    getSession(id) {
+        if (!id)
+            return undefined;
+        return this.sessions.get(id);
+    }
+}

package/dist/auth/token-manager.js

@@ -0,0 +1,27 @@
+import crypto from "crypto";
+export class TokenManager {
+    constructor(ttlMs) {
+        this.ttlMs = ttlMs;
+        this.token = null;
+    }
+    generate() {
+        const token = crypto.randomBytes(32).toString("base64url");
+        this.token = { token, createdAt: Date.now(), consumed: false };
+        return token;
+    }
+    consume(token) {
+        if (!this.token)
+            return false;
+        if (this.token.consumed)
+            return false;
+        if (Date.now() - this.token.createdAt > this.ttlMs)
+            return false;
+        if (token !== this.token.token)
+            return false;
+        this.token.consumed = true;
+        return true;
+    }
+    peek() {
+        return this.token?.token ?? null;
+    }
+}