@index365/cli 0.1.1 → 0.2.0

package/README.md

@@ -8,14 +8,12 @@ index365 runs two audits: **AI-Readiness** (how well AI agents and AI search can
 
 ```bash
 npm install -g @index365/cli
-# or run without installing:
-npx @index365/cli --help
 ```
 
 ## Quickstart
 
 ```bash
-index365 login            # paste an i365_ key from the dashboard (Org settings -> API keys)
+index365 login --web      # sign in through your browser (no key to copy/paste)
 index365 doctor           # verify auth, scopes, and API reachability
 index365 projects list    # find a projectId
 index365 runs start --project <id> --wait   # run an AI-readiness audit, wait for the score
@@ -25,6 +23,8 @@ index365 findings list --run <runId>        # triage findings
 index365 findings get --run <runId> <findingId>   # full detail + remediation
 ```
 
+`index365 login --web` opens your browser, signs you in on the dashboard, and saves a new key automatically (loopback + PKCE, so the secret never travels through a URL). For CI or headless machines, use `index365 login` to paste an `i365_` key from the dashboard API Keys page, or set `INDEX365_API_KEY`.
+
 Add `--json` to any command for machine-readable output. Keys live at `~/.config/index365/config.json` (mode 0600); `INDEX365_API_KEY` overrides the file.
 
 ## Exit codes

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@index365/cli",
-	"version": "0.1.1",
+	"version": "0.2.0",
 	"description": "index365 CLI - run AI-readiness and marketing-signal audits and read findings from your terminal, CI, or agents. Wraps the public /api/v1.",
 	"type": "module",
 	"license": "MIT",

package/src/cli.mjs

@@ -11,8 +11,15 @@ import {
 	resolveSettings,
 	writeConfigFile,
 } from "./config.mjs";
+import {
+	defaultOpenUrl,
+	defaultStartLoopback,
+	generatePkcePair,
+	generateStateNonce,
+	webLogin,
+} from "./web-login.mjs";
 
-export const CLI_VERSION = "0.1.1";
+export const CLI_VERSION = "0.2.0";
 
 const HELP = `index365 - website audits from your terminal, CI, or agents
 
@@ -20,19 +27,19 @@ USAGE
   index365 <command> [options]
 
 COMMANDS
-  login              Save an API key (prompts; or --key / INDEX365_API_KEY)
+  login              Sign in via browser (--web), or save an API key (prompts; or --key / INDEX365_API_KEY)
   logout             Remove the saved API key
   doctor             Verify auth, scopes, API reachability, contract version
   projects list      List projects in your organization
   projects create    Create a project (--domain <domain> [--name <name>])
   projects delete    Delete a project (<projectId> --confirm <domain>)
-  runs start         Start a paid AI-readiness audit (--project <id>, optional --wait)
+  runs start         Start a paid AI-readiness audit (--project <id>, optional --url <url> to audit a specific page, optional --wait)
   runs get           Show one run (<runId>)
   findings list      List findings for a run (--run <id>)
   findings get       Show one finding (--run <id> <findingId>)
   reports context    Compact agent report context for a run (<runId>)
-  reports download   Download the PDF report to .index365/ (<runId> [--output <file>])
-  marketing run      Start a Marketing Signal audit (--project <id>, optional --wait)
+  reports download   Save the full report JSON (context + findings) to .index365/ (<runId> [--output <file>])
+  marketing run      Start a Marketing Signal audit (--project <id>, optional --url <url> to audit a specific page, optional --wait)
   marketing report   Latest Marketing Signal report for a project (--project <id>)
   marketing findings Marketing findings (--run <id> | --project <id>, optional --stage)
   integrations list  Connected-signal providers + status (--project <id>)
@@ -47,8 +54,11 @@ EXIT CODES
   0 ok · 1 error · 2 usage · 3 auth · 4 not found · 5 quota/conflict/rate
 
 AUTH
-  Keys are created from any active paid plan's workspace in the dashboard
-  (Org settings -> API keys) and stored at ~/.config/index365/config.json
+  'index365 login --web' opens your browser, signs you in on the dashboard,
+  and saves a new key automatically (loopback + PKCE; no key to copy/paste).
+  For CI/headless, 'index365 login' takes a key from --key / INDEX365_API_KEY,
+  or you can create one from the dashboard API Keys page (every plan, including
+  Free). Either way the key is stored at ~/.config/index365/config.json
   (0600). INDEX365_API_KEY overrides the file.
 `;
 
@@ -91,9 +101,29 @@ async function promptForKey(io) {
 			EXIT.USAGE,
 		);
 	}
-	const rl = createInterface({ input, output });
+	const rl = createInterface({ input, output, terminal: true });
+	// Mask the key as it is typed/pasted so it is not echoed to the terminal
+	// (audit #9). Masking uses readline's `_writeToOutput` echo hook (stable
+	// across Node 18-22 and the basis of most prompt libraries). The prompt text
+	// is written before muting; only the secret keystrokes are suppressed.
+	let muted = false;
+	const writeToOutput = rl._writeToOutput?.bind(rl);
+	if (typeof writeToOutput === "function") {
+		rl._writeToOutput = (chunk) => {
+			if (muted && chunk !== "\n" && chunk !== "\r\n") return;
+			writeToOutput(chunk);
+		};
+	} else {
+		// Never fail SILENTLY: if a runtime lacks the echo hook, tell the user the
+		// key will be visible so they can choose --key / INDEX365_API_KEY instead.
+		output.write("Note: input will be visible in this terminal. Ctrl+C to cancel and use --key.\n");
+	}
 	try {
-		const answer = await rl.question("Paste your API key (i365_...): ");
+		const pending = rl.question("Paste your API key (i365_...): ");
+		muted = true;
+		const answer = await pending;
+		muted = false;
+		output.write("\n");
 		return answer.trim();
 	} finally {
 		rl.close();
@@ -101,7 +131,11 @@ async function promptForKey(io) {
 }
 
 async function cmdLogin(argv, io, env) {
-	const { values } = parse(argv, { key: { type: "string" } });
+	const { values } = parse(argv, {
+		key: { type: "string" },
+		web: { type: "boolean", default: false },
+	});
+	if (values.web) return cmdLoginWeb(values, io, env);
 	const key = (values.key ?? env.INDEX365_API_KEY ?? "").trim() || (await promptForKey(io));
 	if (!key.startsWith("i365_")) {
 		throw new CliError("That does not look like an index365 API key (i365_...).", EXIT.USAGE);
@@ -128,6 +162,42 @@ async function cmdLogin(argv, io, env) {
 	return EXIT.OK;
 }
 
+/**
+ * `index365 login --web` — open the browser, complete the loopback + PKCE
+ * consent on the dashboard, and save the minted key to the same 0600 config the
+ * paste flow writes. The secret only ever arrives in the exchange response body;
+ * it is never printed.
+ */
+async function cmdLoginWeb(values, io, env) {
+	const settings = settingsFor(values, env);
+	const token = await webLogin({ apiUrl: settings.apiUrl, json: values.json }, io);
+
+	const config = readConfigFile(env);
+	config.apiKey = token.secret;
+	if (values["api-url"]) config.apiUrl = settings.apiUrl;
+	const file = writeConfigFile(config, env);
+
+	if (values.json) {
+		printJson(io, {
+			ok: true,
+			configPath: file,
+			keyName: token.keyName,
+			keyPrefix: token.keyPrefix,
+			scopes: token.scopes,
+			organizationId: token.organizationId,
+			organizationSlug: token.organizationSlug ?? null,
+		});
+	} else {
+		out(
+			io,
+			`Logged in as '${token.keyName}' (${token.keyPrefix}…) for org ${token.organizationSlug ?? token.organizationId}.`,
+		);
+		out(io, `Scopes: ${token.scopes.join(", ")}`);
+		out(io, `Saved to ${file} (0600).`);
+	}
+	return EXIT.OK;
+}
+
 async function cmdLogout(argv, io, env) {
 	const { values } = parse(argv);
 	const removed = deleteConfigFile(env);
@@ -295,11 +365,15 @@ async function cmdRuns(argv, io, env) {
 	if (sub === "start") {
 		const { values } = parse(rest, {
 			project: { type: "string" },
+			url: { type: "string" },
 			"idempotency-key": { type: "string" },
 			wait: { type: "boolean", default: false },
 		});
 		if (!values.project) {
-			throw new CliError("Usage: index365 runs start --project <projectId> [--wait]", EXIT.USAGE);
+			throw new CliError(
+				"Usage: index365 runs start --project <projectId> [--url <url>] [--wait]",
+				EXIT.USAGE,
+			);
 		}
 		return startRunAndMaybeWait(values, io, env, "paid_ai_readiness");
 	}
@@ -407,17 +481,42 @@ async function cmdReports(argv, io, env) {
 			throw new CliError("Usage: index365 reports download <runId> [--output <file>]", EXIT.USAGE);
 		}
 		const settings = settingsFor(values, env);
-		const link = await apiRequest(settings, "GET", `/api/v1/runs/${runId}/pdf`, {
-			fetchImpl: io.fetch,
-		});
-		const target = values.output ?? `.index365/index365-audit-${runId}.pdf`;
-		const res = await io.fetch(link.url);
-		if (!res.ok) throw new CliError(`PDF download failed (${res.status}).`, EXIT.ERROR);
-		const buffer = Buffer.from(await res.arrayBuffer());
+		// Save the self-contained report: the compact agent context PLUS every
+		// finding inlined, matching the dashboard's JSON export. (The legacy PDF
+		// download was retired 2026-06-23; the report is served as JSON/Markdown.)
+		let report;
+		try {
+			report = await apiRequest(settings, "GET", `/api/v1/runs/${runId}/report`, {
+				fetchImpl: io.fetch,
+			});
+		} catch (err) {
+			if (err instanceof CliError && err.detail?.code === "results_unavailable") {
+				throw new CliError(
+					`No report export for run ${runId} (e.g. Website Security runs are not served by the report API yet). Try: index365 findings list --run ${runId}`,
+					EXIT.ERROR,
+				);
+			}
+			throw err;
+		}
+		// Page through every finding so the saved file is the full superset.
+		const findings = [];
+		let cursor;
+		do {
+			const page = await apiRequest(settings, "GET", `/api/v1/runs/${runId}/findings`, {
+				fetchImpl: io.fetch,
+				query: cursor ? { cursor } : {},
+			});
+			if (Array.isArray(page?.findings)) findings.push(...page.findings);
+			cursor = page?.pagination?.nextCursor ?? undefined;
+		} while (cursor);
+		const data = { ...report, findings };
+		const body = `${JSON.stringify(data, null, 2)}\n`;
+		const bytes = Buffer.byteLength(body);
+		const target = values.output ?? `.index365/index365-report-${runId}.json`;
 		mkdirSync(dirname(target), { recursive: true });
-		writeFileSync(target, buffer);
-		if (values.json) printJson(io, { ok: true, file: target, bytes: buffer.length });
-		else out(io, `Saved ${target} (${buffer.length} bytes).`);
+		writeFileSync(target, body);
+		if (values.json) printJson(io, { ok: true, file: target, bytes });
+		else out(io, `Saved ${target} (${bytes} bytes).`);
 		return EXIT.OK;
 	}
 	throw new CliError("Usage: index365 reports <context|download>", EXIT.USAGE);
@@ -426,8 +525,16 @@ async function cmdReports(argv, io, env) {
 /** Shared run-start + optional poll loop (AI-readiness and Marketing Signal). */
 async function startRunAndMaybeWait(values, io, env, scanMode) {
 	const settings = settingsFor(values, env);
+	// Every scan audits exactly one URL. `--url` targets a specific same-domain
+	// page; omitted, the run audits the project homepage.
 	let run = await apiRequest(settings, "POST", "/api/v1/runs", {
-		body: { projectId: values.project, scanMode },
+		body: {
+			projectId: values.project,
+			scanMode,
+			// Forward an explicitly-provided url even if empty so the API rejects it
+			// (400), instead of silently dropping `--url ""` and running the homepage.
+			...(values.url !== undefined ? { url: values.url } : {}),
+		},
 		idempotencyKey: values["idempotency-key"],
 		fetchImpl: io.fetch,
 	});
@@ -461,12 +568,13 @@ async function cmdMarketing(argv, io, env) {
 	if (sub === "run") {
 		const { values } = parse(rest, {
 			project: { type: "string" },
+			url: { type: "string" },
 			"idempotency-key": { type: "string" },
 			wait: { type: "boolean", default: false },
 		});
 		if (!values.project) {
 			throw new CliError(
-				"Usage: index365 marketing run --project <projectId> [--wait]",
+				"Usage: index365 marketing run --project <projectId> [--url <url>] [--wait]",
 				EXIT.USAGE,
 			);
 		}
@@ -595,7 +703,10 @@ async function cmdMcp(argv, io, env) {
 	out(io, "Codex / Cursor / any MCP host (JSON):");
 	out(io, JSON.stringify({ mcpServers: { index365: serverConfig } }, null, 2));
 	out(io, "");
-	out(io, "The MCP server is read-only by default and calls the same /api/v1 as this CLI.");
+	out(
+		io,
+		"The MCP server calls the same /api/v1 as this CLI, with whatever scopes your i365_ key carries (full scope by default).",
+	);
 	return EXIT.OK;
 }
 
@@ -655,5 +766,10 @@ export function defaultIo() {
 		fetch: (...args) => fetch(...args),
 		sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
 		now: () => Date.now(),
+		// Browser-OAuth primitives for `login --web` (injectable so tests stay hermetic).
+		pkce: () => generatePkcePair(),
+		nonce: () => generateStateNonce(),
+		openUrl: (url) => defaultOpenUrl(url),
+		startLoopback: () => defaultStartLoopback(),
 	};
 }

package/src/client.mjs

@@ -50,8 +50,14 @@ export async function apiRequest(settings, method, apiPath, options = {}) {
 
 	const headers = {
 		authorization: `Bearer ${settings.apiKey}`,
-		"user-agent": "index365-cli/0.1.0",
+		"user-agent": "index365-cli/0.2.0",
 	};
+	// Optional source tag so a wrapping skill can attribute its traffic
+	// (e.g. INDEX365_CLIENT=skill/index365-audit-and-fix). The server validates it.
+	const clientTag = process.env.INDEX365_CLIENT;
+	if (typeof clientTag === "string" && clientTag.trim()) {
+		headers["x-index365-client"] = clientTag.trim();
+	}
 	if (body !== undefined) headers["content-type"] = "application/json";
 	if (idempotencyKey) headers["idempotency-key"] = idempotencyKey;
 

package/src/web-login.mjs

@@ -0,0 +1,242 @@
+import { spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { hostname } from "node:os";
+import { CliError, EXIT, exitCodeForStatus } from "./client.mjs";
+
+/**
+ * `index365 login --web` — browser OAuth for the CLI (loopback + PKCE, RFC 8252).
+ *
+ * The pure, dependency-free pieces (URL building, PKCE/state generation, the
+ * token exchange) live here alongside the default side-effecting primitives
+ * (loopback server, browser opener). Every side effect is passed in through `io`
+ * so the orchestration in `webLogin` stays hermetically testable.
+ *
+ * Flow: generate a PKCE verifier/challenge + state → start a loopback server on
+ * 127.0.0.1:<random> → open the browser to the dashboard consent screen →
+ * receive the single-use code on the loopback → bounce the browser to the hosted
+ * success page → exchange the code + verifier for a scoped key at
+ * /api/v1/cli/token. The secret only ever arrives in the exchange RESPONSE body,
+ * never in a URL.
+ */
+
+/** Five minutes is plenty for sign-in + consent; after that we stop waiting. */
+export const WEB_LOGIN_TIMEOUT_MS = 5 * 60_000;
+
+/** PKCE verifier (43 base64url chars ≈ 256 bits) + its S256 challenge. */
+export function generatePkcePair() {
+	const verifier = randomBytes(32).toString("base64url");
+	const challenge = createHash("sha256").update(verifier).digest("base64url");
+	return { verifier, challenge };
+}
+
+/** Opaque anti-forgery nonce echoed back on the callback. */
+export function generateStateNonce() {
+	return randomBytes(16).toString("base64url");
+}
+
+/** Human label for the minted key, e.g. "index365 CLI on Pauls-MBP". */
+export function defaultClientName() {
+	let host = "";
+	try {
+		host = hostname();
+	} catch {
+		host = "";
+	}
+	return host ? `index365 CLI on ${host}` : "index365 CLI";
+}
+
+/** Build the dashboard consent URL the browser opens. */
+export function buildAuthorizeUrl(apiUrl, { redirectUri, codeChallenge, state, clientName }) {
+	const url = new URL(`${apiUrl}/dashboard/cli/authorize`);
+	url.searchParams.set("response_type", "code");
+	url.searchParams.set("redirect_uri", redirectUri);
+	url.searchParams.set("code_challenge", codeChallenge);
+	url.searchParams.set("code_challenge_method", "S256");
+	url.searchParams.set("state", state);
+	if (clientName) url.searchParams.set("client_name", clientName);
+	return url.toString();
+}
+
+/** Swap the authorization code + PKCE verifier for a scoped credential. */
+export async function exchangeCode(apiUrl, { code, codeVerifier, redirectUri, fetchImpl = fetch }) {
+	let response;
+	try {
+		response = await fetchImpl(`${apiUrl}/api/v1/cli/token`, {
+			method: "POST",
+			headers: { "content-type": "application/json", "user-agent": "index365-cli/0.2.0" },
+			body: JSON.stringify({ code, code_verifier: codeVerifier, redirect_uri: redirectUri }),
+		});
+	} catch (err) {
+		throw new CliError(`Could not reach ${apiUrl}: ${err.message}`, EXIT.ERROR);
+	}
+	const text = await response.text();
+	let parsed = null;
+	try {
+		parsed = text ? JSON.parse(text) : null;
+	} catch {
+		parsed = null;
+	}
+	if (!response.ok) {
+		const errorCode = parsed?.error?.code ?? `http_${response.status}`;
+		const message = parsed?.error?.message ?? `Token exchange failed (status ${response.status}).`;
+		throw new CliError(
+			`${errorCode}: ${message}`,
+			exitCodeForStatus(response.status),
+			parsed?.error,
+		);
+	}
+	if (!parsed?.secret) {
+		throw new CliError("Token exchange returned no credential.", EXIT.ERROR);
+	}
+	return parsed;
+}
+
+/**
+ * Default loopback server: listens on 127.0.0.1:0, resolves the single-use code
+ * from the first `/callback` request, bounces the browser to the success page,
+ * and rejects on state mismatch or timeout.
+ */
+export function defaultStartLoopback() {
+	return new Promise((resolve, reject) => {
+		const server = createServer();
+		server.on("error", reject);
+		server.listen(0, "127.0.0.1", () => {
+			const address = server.address();
+			const port = typeof address === "object" && address ? address.port : 0;
+			resolve({
+				port,
+				waitForCallback: ({ state, timeoutMs = WEB_LOGIN_TIMEOUT_MS, successUrl }) =>
+					new Promise((res, rej) => {
+						const timer = setTimeout(() => {
+							rej(new CliError("Timed out waiting for browser authorization.", EXIT.ERROR));
+						}, timeoutMs);
+						const fail = (response, message, cliError) => {
+							response.writeHead(400, { "content-type": "text/plain" });
+							response.end(`${message} You can close this window and return to your terminal.`);
+							rej(cliError);
+						};
+						const onRequest = (req, response) => {
+							const url = new URL(req.url, `http://127.0.0.1:${port}`);
+							if (url.pathname !== "/callback") {
+								response.writeHead(404);
+								response.end();
+								return;
+							}
+							clearTimeout(timer);
+							server.off("request", onRequest);
+							// Validate the state nonce BEFORE the browser is told anything
+							// succeeded — a forged/replayed callback must not land on the
+							// branded success page.
+							const returnedState = url.searchParams.get("state");
+							if (state && returnedState !== state) {
+								fail(
+									response,
+									"Authorization failed: state mismatch.",
+									new CliError("State mismatch on the authorization callback.", EXIT.AUTH),
+								);
+								return;
+							}
+							const error = url.searchParams.get("error");
+							if (error) {
+								// The user declined (or the consent screen errored): show a neutral
+								// close-this-window page, not the success screen.
+								response.writeHead(200, { "content-type": "text/plain" });
+								response.end(
+									"Authorization was not completed. You can close this window and return to your terminal.",
+								);
+								res({ error });
+								return;
+							}
+							const code = url.searchParams.get("code");
+							if (!code) {
+								fail(
+									response,
+									"Authorization failed: no code was returned.",
+									new CliError("No authorization code in the callback.", EXIT.AUTH),
+								);
+								return;
+							}
+							// Only a valid, state-matched code lands on the branded success page.
+							response.writeHead(302, { location: successUrl });
+							response.end();
+							res({ code });
+						};
+						server.on("request", onRequest);
+					}),
+				close: () => server.close(),
+			});
+		});
+	});
+}
+
+/** Default browser opener (best-effort; the caller also prints the URL). */
+export function defaultOpenUrl(url) {
+	return new Promise((resolve) => {
+		const platform = process.platform;
+		const command = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
+		const args = platform === "win32" ? ["/c", "start", "", url] : [url];
+		try {
+			const child = spawn(command, args, { stdio: "ignore", detached: true });
+			child.on("error", () => resolve(false));
+			child.unref();
+			resolve(true);
+		} catch {
+			resolve(false);
+		}
+	});
+}
+
+/**
+ * Run the browser-OAuth flow and return the token-exchange response
+ * ({ secret, keyName, keyPrefix, scopes, organizationId, organizationSlug }).
+ * Saving the credential to config is the caller's job (cmdLogin), so the config
+ * writer stays in one place. Throws CliError on failure/cancel.
+ */
+export async function webLogin({ apiUrl, json }, io) {
+	const { verifier, challenge } = io.pkce();
+	const state = io.nonce();
+	const clientName = defaultClientName();
+	const loopback = await io.startLoopback();
+	const redirectUri = `http://127.0.0.1:${loopback.port}/callback`;
+	const authorizeUrl = buildAuthorizeUrl(apiUrl, {
+		redirectUri,
+		codeChallenge: challenge,
+		state,
+		clientName,
+	});
+	const successUrl = `${apiUrl}/dashboard/cli/success`;
+
+	// The browser opener is best-effort, so the authorize URL is ALWAYS surfaced
+	// for manual paste — to stderr in --json mode so stdout stays machine-readable,
+	// otherwise a host with no opener would hang until timeout with no way to continue.
+	const note = json ? io.stderr : io.stdout;
+	note("Opening your browser to authorize index365...");
+	note(`If it does not open automatically, visit:\n  ${authorizeUrl}`);
+	try {
+		await io.openUrl(authorizeUrl);
+	} catch {
+		// Best-effort: the URL was printed above for manual paste.
+	}
+
+	let result;
+	try {
+		result = await loopback.waitForCallback({ state, timeoutMs: WEB_LOGIN_TIMEOUT_MS, successUrl });
+	} finally {
+		loopback.close();
+	}
+
+	if (result.error) {
+		if (result.error === "access_denied") {
+			throw new CliError("Authorization was cancelled in the browser.", EXIT.AUTH);
+		}
+		throw new CliError(`Authorization failed (${result.error}).`, EXIT.AUTH);
+	}
+
+	return exchangeCode(apiUrl, {
+		code: result.code,
+		codeVerifier: verifier,
+		redirectUri,
+		fetchImpl: io.fetch,
+	});
+}