Add JWT authentication and firebolt-auth CLI

.env.example

@@ -1,5 +1,6 @@
 FIREBOLT_CLIENT_ID=
 FIREBOLT_CLIENT_SECRET=
+FIREBOLT_JWT=
 FIREBOLT_ACCOUNT=
 FIREBOLT_DATABASE=
 FIREBOLT_ENGINE_NAME=

package.json

@@ -4,11 +4,14 @@
   "description": "Official firebolt Node.JS sdk",
   "main": "./build/src/index.js",
   "types": "./build/src/index.d.ts",
+  "bin": {
+    "firebolt-auth": "./build/src/cli/firebolt-auth.js"
+  },
   "engines": {
     "node": ">=16.0"
   },
   "scripts": {
-    "build": "rm -fr ./build && tsc -p tsconfig.lib.json",
+    "build": "rm -fr ./build && tsc -p tsconfig.lib.json && chmod +x ./build/src/cli/firebolt-auth.js",
     "release": "standard-version",
     "test": "jest",
     "test:ci": "node --expose-gc ./node_modules/.bin/jest --ci --bail",
@@ -46,6 +49,7 @@
     "@types/json-bigint": "^1.0.1",
     "abort-controller": "^3.0.0",
     "agentkeepalive": "^4.5.0",
+    "commander": "^14.0.3",
     "json-bigint": "^1.0.0",
     "node-fetch": "^2.6.6",
     "rwlock": "^5.0.0"

src/auth/jwt.ts

@@ -0,0 +1,106 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+
+const TOKEN_FILE_DIR = ".firebolt";
+const TOKEN_FILE_NAME = "token";
+const JWT_ENV_VAR_NAME = "FIREBOLT_JWT";
+const EXPIRY_BUFFER_MS = 30_000;
+
+export type ResolvedJwt = {
+  token: string;
+  expiresAtMs: number;
+};
+
+export function getTokenFilePath(): string {
+  return path.join(os.homedir(), TOKEN_FILE_DIR, TOKEN_FILE_NAME);
+}
+
+/**
+ * Decode the payload of a JWT (no signature verification) and extract the `exp` claim.
+ * Returns the expiry as a Unix‐millisecond timestamp, or undefined if missing/invalid.
+ */
+export function extractJwtExpiry(token: string): number | undefined {
+  const parts = token.split(".");
+  if (parts.length !== 3) return undefined;
+
+  try {
+    const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString());
+    if (typeof payload.exp === "number") {
+      return payload.exp * 1000; // seconds → ms
+    }
+  } catch {
+    // malformed token – fall through
+  }
+  return undefined;
+}
+
+export function isTokenExpired(expiresAtMs: number): boolean {
+  return Date.now() >= expiresAtMs - EXPIRY_BUFFER_MS;
+}
+
+export function getJwtFromEnv(): string | undefined {
+  const value = process.env[JWT_ENV_VAR_NAME];
+  return value && value.trim() !== "" ? value.trim() : undefined;
+}
+
+export function getStoredTokenFromFile(): string | undefined {
+  const filePath = getTokenFilePath();
+  try {
+    const content = fs.readFileSync(filePath, "utf-8").trim();
+    return content !== "" ? content : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolve a JWT from env var or file.
+ * Priority: FIREBOLT_JWT env var > ~/.firebolt/token file.
+ * Returns undefined if no valid (non‑expired) token is found.
+ */
+export function resolveJwt(): ResolvedJwt | undefined {
+  const sources: Array<() => string | undefined> = [
+    getJwtFromEnv,
+    getStoredTokenFromFile
+  ];
+
+  for (const source of sources) {
+    const token = source();
+    if (!token) continue;
+
+    const expiresAtMs = extractJwtExpiry(token);
+    if (expiresAtMs === undefined) continue;
+    if (isTokenExpired(expiresAtMs)) continue;
+
+    return { token, expiresAtMs };
+  }
+
+  return undefined;
+}
+
+/**
+ * Write a token string to ~/.firebolt/token with secure permissions.
+ */
+export function writeTokenToFile(token: string): void {
+  const filePath = getTokenFilePath();
+  const dir = path.dirname(filePath);
+
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  }
+
+  fs.writeFileSync(filePath, token, { encoding: "utf-8", mode: 0o600 });
+}
+
+/**
+ * Remove the cached token file if it exists.
+ */
+export function removeTokenFile(): void {
+  const filePath = getTokenFilePath();
+  try {
+    fs.unlinkSync(filePath);
+  } catch {
+    // file doesn't exist – nothing to do
+  }
+}

src/auth/managed.ts

@@ -14,6 +14,7 @@ import {
   noneCache,
   rwLock
 } from "../common/tokenCache";
+import { resolveJwt } from "./jwt";
 
 type Login = {
   access_token: string;
@@ -297,6 +298,14 @@ export class Authenticator {
   }
 
   private async performAuthentication(): Promise<void> {
+    // Check for a JWT (env var or file) before OAuth
+    const jwt = resolveJwt();
+    if (jwt && jwt.token !== this.accessToken) {
+      this.accessToken = jwt.token;
+      this.tokenExpiryTimestampMs = jwt.expiresAtMs;
+      return;
+    }
+
     const options = this.options.auth || this.options;
 
     let auth: TokenInfo;