speqs 0.1.2 → 0.2.0

package/dist/auth.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Browser-based authentication via the Speqs frontend plugin auth flow.
+ * Uses the existing /auth/plugin + /api/plugin/auth/poll infrastructure.
+ */
+export declare function getAppUrl(): string;
+export declare function getSupabaseUrl(): string;
+export declare function getSupabaseAnonKey(): string;
+export declare function decodeJwtExp(token: string): number;
+export declare function isTokenExpired(token: string, bufferSeconds?: number): boolean;
+export declare function login(appUrl?: string): Promise<{
+    accessToken: string;
+    refreshToken: string;
+}>;
+export declare function refreshTokens(refreshToken: string, supabaseUrl?: string, anonKey?: string): Promise<{
+    accessToken: string;
+    refreshToken: string;
+}>;

package/dist/auth.js

@@ -0,0 +1,102 @@
+/**
+ * Browser-based authentication via the Speqs frontend plugin auth flow.
+ * Uses the existing /auth/plugin + /api/plugin/auth/poll infrastructure.
+ */
+import * as crypto from "node:crypto";
+import { execFile } from "node:child_process";
+const POLL_INTERVAL = 2_000;
+const LOGIN_TIMEOUT = 5 * 60 * 1000; // 5 minutes (matches server-side token TTL)
+const DEFAULT_APP_URL = "https://app.speqs.io";
+const DEFAULT_SUPABASE_URL = "https://hngymyxdyamokpbeakps.supabase.co";
+const DEFAULT_SUPABASE_ANON_KEY = "sb_publishable_JlS-HfwNyDqLNbrfbrkUlw_PSdZJdo2";
+export function getAppUrl() {
+    return process.env.SPEQS_APP_URL ?? DEFAULT_APP_URL;
+}
+export function getSupabaseUrl() {
+    return process.env.SPEQS_SUPABASE_URL ?? DEFAULT_SUPABASE_URL;
+}
+export function getSupabaseAnonKey() {
+    return process.env.SPEQS_SUPABASE_ANON_KEY ?? DEFAULT_SUPABASE_ANON_KEY;
+}
+// --- Browser open ---
+function openBrowser(url) {
+    if (process.platform === "win32") {
+        execFile("cmd", ["/c", "start", "", url]);
+    }
+    else if (process.platform === "darwin") {
+        execFile("open", [url]);
+    }
+    else {
+        execFile("xdg-open", [url]);
+    }
+}
+// --- JWT decode ---
+export function decodeJwtExp(token) {
+    try {
+        const payload = token.split(".")[1];
+        const decoded = JSON.parse(Buffer.from(payload, "base64url").toString());
+        return decoded.exp;
+    }
+    catch {
+        return 0;
+    }
+}
+export function isTokenExpired(token, bufferSeconds = 300) {
+    const exp = decodeJwtExp(token);
+    if (!exp)
+        return true;
+    return Date.now() / 1000 >= exp - bufferSeconds;
+}
+// --- Login via browser polling ---
+export async function login(appUrl) {
+    const url = appUrl ?? getAppUrl();
+    const state = crypto.randomBytes(32).toString("hex");
+    const loginUrl = `${url}/auth/plugin?state=${state}`;
+    console.log("Opening browser to sign in...");
+    console.log(`If the browser doesn't open, visit:\n  ${loginUrl}\n`);
+    openBrowser(loginUrl);
+    console.log("Waiting for authentication...");
+    const deadline = Date.now() + LOGIN_TIMEOUT;
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, POLL_INTERVAL));
+        try {
+            const resp = await fetch(`${url}/api/plugin/auth/poll?state=${state}`, {
+                signal: AbortSignal.timeout(10_000),
+            });
+            if (resp.status === 200) {
+                const data = await resp.json();
+                if (data.status === "complete" && data.access_token && data.refresh_token) {
+                    return { accessToken: data.access_token, refreshToken: data.refresh_token };
+                }
+            }
+            // 202 = pending, keep polling
+        }
+        catch {
+            // Network error, keep polling
+        }
+    }
+    throw new Error("Login timed out. Please try again.");
+}
+// --- Token refresh ---
+export async function refreshTokens(refreshToken, supabaseUrl, anonKey) {
+    const url = supabaseUrl ?? getSupabaseUrl();
+    const key = anonKey ?? getSupabaseAnonKey();
+    const resp = await fetch(`${url}/auth/v1/token?grant_type=refresh_token`, {
+        method: "POST",
+        headers: {
+            apikey: key,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ refresh_token: refreshToken }),
+        signal: AbortSignal.timeout(10_000),
+    });
+    if (!resp.ok) {
+        const body = await resp.text().catch(() => "");
+        throw new Error(`Token refresh failed (HTTP ${resp.status}): ${body}`);
+    }
+    const data = await resp.json();
+    if (!data.access_token || !data.refresh_token) {
+        throw new Error("Token refresh response missing required fields");
+    }
+    return { accessToken: data.access_token, refreshToken: data.refresh_token };
+}

package/dist/config.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Config persistence for ~/.speqs/config.json
+ */
+export interface SpeqsConfig {
+    access_token?: string;
+    refresh_token?: string;
+    token?: string;
+    [key: string]: string | undefined;
+}
+export declare function loadConfig(): SpeqsConfig;
+export declare function saveConfig(config: SpeqsConfig): void;

package/dist/config.js

@@ -0,0 +1,25 @@
+/**
+ * Config persistence for ~/.speqs/config.json
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+const CONFIG_DIR = path.join(os.homedir(), ".speqs");
+const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
+export function loadConfig() {
+    try {
+        if (fs.existsSync(CONFIG_FILE)) {
+            return JSON.parse(fs.readFileSync(CONFIG_FILE, "utf-8"));
+        }
+    }
+    catch {
+        // Corrupted config — ignore
+    }
+    return {};
+}
+export function saveConfig(config) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    const tmp = CONFIG_FILE + ".tmp";
+    fs.writeFileSync(tmp, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
+    fs.renameSync(tmp, CONFIG_FILE);
+}

package/dist/index.js

@@ -2,12 +2,42 @@
 import { createRequire } from "node:module";
 import { program, Option } from "commander";
 import { runTunnel } from "./tunnel.js";
+import { login, getAppUrl } from "./auth.js";
+import { loadConfig, saveConfig } from "./config.js";
 const require = createRequire(import.meta.url);
 const { version } = require("../package.json");
 program
     .name("speqs")
     .description("Speqs CLI tools")
     .version(version);
+program
+    .command("login")
+    .description("Authenticate with Speqs via your browser")
+    .action(async () => {
+    try {
+        const tokens = await login(getAppUrl());
+        const config = loadConfig();
+        config.access_token = tokens.accessToken;
+        config.refresh_token = tokens.refreshToken;
+        saveConfig(config);
+        console.log("\nLogin successful!");
+    }
+    catch (e) {
+        console.error(`Login failed: ${e instanceof Error ? e.message : e}`);
+        process.exit(1);
+    }
+});
+program
+    .command("logout")
+    .description("Remove saved authentication credentials")
+    .action(() => {
+    const config = loadConfig();
+    delete config.access_token;
+    delete config.refresh_token;
+    delete config.token;
+    saveConfig(config);
+    console.log("Logged out.");
+});
 program
     .command("tunnel")
     .description("Expose your localhost to Speqs via a Cloudflare tunnel")

package/dist/tunnel.js

@@ -2,33 +2,16 @@
  * Localhost tunnel CLI — wraps cloudflared and registers with Speqs backend.
  */
 import { spawn, execSync } from "node:child_process";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import * as os from "node:os";
 import * as readline from "node:readline";
+import { loadConfig, saveConfig } from "./config.js";
+import { refreshTokens, isTokenExpired, decodeJwtExp } from "./auth.js";
 const TUNNEL_URL_PATTERN = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
 const HEARTBEAT_INTERVAL = 30_000;
 const MAX_HEARTBEAT_FAILURES = 3;
 const CLOUDFLARED_STARTUP_TIMEOUT = 30_000;
 const DEFAULT_API_URL = "https://api.speqs.io";
 const API_BASE = "/api/v1";
-const CONFIG_DIR = path.join(os.homedir(), ".speqs");
-const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
-function loadConfig() {
-    try {
-        if (fs.existsSync(CONFIG_FILE)) {
-            return JSON.parse(fs.readFileSync(CONFIG_FILE, "utf-8"));
-        }
-    }
-    catch {
-        // Corrupted config — ignore
-    }
-    return {};
-}
-function saveConfig(config) {
-    fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
-    fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
-}
+// --- Token resolution ---
 async function verifyToken(token, apiUrl) {
     try {
         const resp = await fetch(`${apiUrl}${API_BASE}/tunnel/active`, {
@@ -58,20 +41,62 @@ function prompt(question) {
         });
     });
 }
+/**
+ * Resolve an access token, refreshing if needed.
+ * Returns both the token and a mutable holder for runtime refresh.
+ */
 async function resolveToken(tokenArg, apiUrl) {
+    // 1. Explicit token argument
     if (tokenArg)
-        return tokenArg;
+        return { token: tokenArg, refresh: null };
+    // 2. Environment variable
     const envToken = process.env.SPEQS_TOKEN;
     if (envToken)
-        return envToken;
+        return { token: envToken, refresh: null };
+    // 3. Saved config with refresh token
     const config = loadConfig();
+    if (config.access_token && config.refresh_token) {
+        let accessToken = config.access_token;
+        // Refresh if expired or close to expiry
+        if (isTokenExpired(accessToken)) {
+            try {
+                console.log("Refreshing access token...");
+                const tokens = await refreshTokens(config.refresh_token);
+                accessToken = tokens.accessToken;
+                config.access_token = tokens.accessToken;
+                config.refresh_token = tokens.refreshToken;
+                saveConfig(config);
+            }
+            catch (e) {
+                console.error(`Token refresh failed: ${e instanceof Error ? e.message : e}`);
+                console.error('Run "speqs login" to re-authenticate.\n');
+            }
+        }
+        if (await verifyToken(accessToken, apiUrl)) {
+            // Return with refresh capability for long-running tunnel
+            const doRefresh = async () => {
+                const cfg = loadConfig();
+                if (!cfg.refresh_token)
+                    throw new Error("No refresh token");
+                const tokens = await refreshTokens(cfg.refresh_token);
+                cfg.access_token = tokens.accessToken;
+                cfg.refresh_token = tokens.refreshToken;
+                saveConfig(cfg);
+                return tokens.accessToken;
+            };
+            return { token: accessToken, refresh: doRefresh };
+        }
+        console.error('Saved token is invalid. Run "speqs login" to re-authenticate.\n');
+    }
+    // 4. Legacy saved token (no refresh token)
     if (config.token) {
         if (await verifyToken(config.token, apiUrl)) {
-            return config.token;
+            return { token: config.token, refresh: null };
         }
         console.error("Saved token is invalid or expired.\n");
     }
-    // Interactive prompt
+    // 5. Interactive prompt (legacy fallback)
+    console.log('Tip: Run "speqs login" for browser-based authentication with auto-refresh.\n');
     console.log("You can find your token in the simulation view.\n");
     while (true) {
         const token = await prompt("Paste your token: ");
@@ -82,7 +107,7 @@ async function resolveToken(tokenArg, apiUrl) {
         if (await verifyToken(token, apiUrl)) {
             config.token = token;
             saveConfig(config);
-            return token;
+            return { token, refresh: null };
         }
         console.error("Invalid token. Try again.\n");
     }
@@ -171,7 +196,7 @@ async function deregisterTunnel(apiUrl, token) {
         console.error(`Warning: Failed to deregister tunnel: ${e}`);
     }
 }
-function startHeartbeat(apiUrl, token, onFatal) {
+function startHeartbeat(apiUrl, getToken, doRefresh, onTokenRefreshed, onFatal) {
     let consecutiveFailures = 0;
     let stopped = false;
     const interval = setInterval(async () => {
@@ -180,9 +205,30 @@ function startHeartbeat(apiUrl, token, onFatal) {
         try {
             const resp = await fetch(`${apiUrl}${API_BASE}/tunnel/heartbeat`, {
                 method: "POST",
-                headers: { Authorization: `Bearer ${token}` },
+                headers: { Authorization: `Bearer ${getToken()}` },
                 signal: AbortSignal.timeout(10_000),
             });
+            // If 401 and we can refresh, try once
+            if (resp.status === 401 && doRefresh) {
+                try {
+                    const newToken = await doRefresh();
+                    onTokenRefreshed(newToken);
+                    console.log("Token refreshed.");
+                    // Retry heartbeat with new token
+                    const retry = await fetch(`${apiUrl}${API_BASE}/tunnel/heartbeat`, {
+                        method: "POST",
+                        headers: { Authorization: `Bearer ${newToken}` },
+                        signal: AbortSignal.timeout(10_000),
+                    });
+                    if (!retry.ok)
+                        throw new Error(`HTTP ${retry.status}`);
+                    consecutiveFailures = 0;
+                    return;
+                }
+                catch (refreshErr) {
+                    console.error(`Token refresh failed: ${refreshErr}`);
+                }
+            }
             if (!resp.ok)
                 throw new Error(`HTTP ${resp.status}`);
             consecutiveFailures = 0;
@@ -205,13 +251,55 @@ function startHeartbeat(apiUrl, token, onFatal) {
         },
     };
 }
+/**
+ * Schedule a proactive token refresh before the JWT expires.
+ * Refreshes 10 minutes before expiry.
+ */
+function scheduleProactiveRefresh(token, doRefresh, onTokenRefreshed) {
+    if (!doRefresh)
+        return { stop: () => { } };
+    const exp = decodeJwtExp(token);
+    if (!exp)
+        return { stop: () => { } };
+    const refreshAt = (exp - 600) * 1000; // 10 min before expiry
+    const delay = refreshAt - Date.now();
+    if (delay <= 0)
+        return { stop: () => { } };
+    const timer = setTimeout(async () => {
+        try {
+            const newToken = await doRefresh();
+            onTokenRefreshed(newToken);
+            console.log("Token proactively refreshed.");
+            // Schedule next refresh for the new token
+            scheduleProactiveRefresh(newToken, doRefresh, onTokenRefreshed);
+        }
+        catch (e) {
+            console.error(`Proactive token refresh failed: ${e}`);
+        }
+    }, delay);
+    return { stop: () => clearTimeout(timer) };
+}
 // --- Main ---
 export async function runTunnel(port, tokenArg, apiUrlArg) {
     const apiUrl = resolveApiUrl(apiUrlArg);
     if (apiUrl !== DEFAULT_API_URL) {
         console.log(`Using API: ${apiUrl}`);
     }
-    const token = await resolveToken(tokenArg, apiUrl);
+    const resolved = await resolveToken(tokenArg, apiUrl);
+    let currentToken = resolved.token;
+    const onTokenRefreshed = (newToken) => {
+        currentToken = newToken;
+    };
+    // Serialize refresh calls to prevent concurrent use of single-use refresh tokens
+    let refreshInFlight = null;
+    const serializedRefresh = resolved.refresh
+        ? async () => {
+            if (refreshInFlight)
+                return refreshInFlight;
+            refreshInFlight = resolved.refresh().finally(() => { refreshInFlight = null; });
+            return refreshInFlight;
+        }
+        : null;
     checkCloudflared();
     let cfResult;
     try {
@@ -222,30 +310,33 @@ export async function runTunnel(port, tokenArg, apiUrlArg) {
         process.exit(1);
     }
     const { process: cfProcess, tunnelUrl } = cfResult;
-    await registerTunnel(apiUrl, token, tunnelUrl, port);
+    await registerTunnel(apiUrl, currentToken, tunnelUrl, port);
     let shuttingDown = false;
+    const heartbeat = startHeartbeat(apiUrl, () => currentToken, serializedRefresh, onTokenRefreshed, async () => {
+        await deregisterTunnel(apiUrl, currentToken);
+        cfProcess.kill();
+        process.exit(1);
+    });
+    const proactiveRefresh = scheduleProactiveRefresh(currentToken, serializedRefresh, onTokenRefreshed);
     const shutdown = async () => {
         if (shuttingDown)
             process.exit(1);
         shuttingDown = true;
         console.log("\nShutting down...");
         heartbeat.stop();
+        proactiveRefresh.stop();
         cfProcess.kill();
-        await deregisterTunnel(apiUrl, token);
+        await deregisterTunnel(apiUrl, currentToken);
         process.exit(0);
     };
-    const heartbeat = startHeartbeat(apiUrl, token, async () => {
-        await deregisterTunnel(apiUrl, token);
-        cfProcess.kill();
-        process.exit(1);
-    });
     process.on("SIGINT", shutdown);
     process.on("SIGTERM", shutdown);
     console.log("\nPress Ctrl+C to disconnect.\n");
     cfProcess.on("exit", async () => {
         if (!shuttingDown) {
             heartbeat.stop();
-            await deregisterTunnel(apiUrl, token);
+            proactiveRefresh.stop();
+            await deregisterTunnel(apiUrl, currentToken);
             process.exit(0);
         }
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speqs",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "The command-line interface for Speqs",
   "type": "module",
   "bin": {