@falldownthesystem/devtool 0.5.0 → 0.6.1

package/src/clients/confluence.js

@@ -1,171 +1,170 @@
-import { get } from '../config/store.js';
-
-const deployments = new Map();
-
-// Custom domains hide the atlassian.net hostname, so anything else is probed:
-// Atlassian's edge answers tenant_info anonymously, Server/Data Center does not.
-async function detectDeployment(origin) {
-	if (/\.atlassian\.net$/i.test(new URL(origin).hostname)) return 'cloud';
-	try {
-		const res = await fetch(new URL('/_edge/tenant_info', origin), {
-			headers: { 'Accept': 'application/json' },
-		});
-		if (res.ok && (await res.json()).cloudId) return 'cloud';
-	} catch {
-		// An unreachable or non-JSON probe means no Atlassian edge; the real request reports connection errors.
-	}
-	return 'server';
-}
-
-async function connect() {
-	const base = new URL(get('confluence.baseUrl'));
-	if (!deployments.has(base.origin)) deployments.set(base.origin, detectDeployment(base.origin));
-	const kind = await deployments.get(base.origin);
-	// Cloud always serves Confluence under /wiki; Server/Data Center keeps its own context path.
-	const path = kind === 'cloud' ? '/wiki' : base.pathname.replace(/\/+$/, '');
-	return { kind, origin: base.origin, path };
-}
-
-function apiUrl(conn, path) {
-	return new URL(`${conn.origin}${conn.path}${path}`);
-}
-
-// Cloud v2 links are origin-relative, Server/Data Center links are relative to the context path.
-function nextUrl(conn, link, current) {
-	const contextRelative = conn.kind === 'server'
-		&& link.startsWith('/') && !link.startsWith('//')
-		&& !(conn.path && link.startsWith(`${conn.path}/`));
-	return contextRelative ? apiUrl(conn, link) : new URL(link, current);
-}
-
-// Server/Data Center personal access tokens use Bearer auth; a username switches to Basic.
-function authHeader(conn) {
-	const email = get('confluence.email');
-	const token = get('confluence.token');
-	if (conn.kind === 'server' && !email) return `Bearer ${token}`;
-	return 'Basic ' + Buffer.from(`${email}:${token}`).toString('base64');
-}
-
-async function request(conn, url, params = {}) {
-	if (url.origin !== conn.origin) {
-		throw new Error('Confluence pagination points to a different site. Check confluence.baseUrl.');
-	}
-	for (const [k, v] of Object.entries(params)) {
-		if (v !== undefined && v !== null) url.searchParams.set(k, v);
-	}
-
-	const res = await fetch(url, {
-		headers: {
-			'Authorization': authHeader(conn),
-			'Accept': 'application/json',
-		},
-	});
-
-	if (!res.ok) {
-		const err = new Error(`Confluence API error: ${res.status} ${res.statusText}`);
-		err.status = res.status;
-		err.url = url.toString();
-		throw err;
-	}
-
-	// Server/Data Center answers rejected credentials with a login page instead of a 401.
-	if (!res.headers.get('content-type')?.includes('json')) {
-		const err = new Error('Confluence returned a non-JSON response. Check confluence.baseUrl and confluence.token.');
-		err.url = url.toString();
-		throw err;
-	}
-
-	return res.json();
-}
-
-async function paginate(conn, path, params = {}) {
-	const results = [];
-	let url = apiUrl(conn, path);
-	let data = await request(conn, url, params);
-	results.push(...(data.results || []));
-
-	while (data._links?.next) {
-		url = nextUrl(conn, data._links.next, url);
-		data = await request(conn, url);
-		results.push(...(data.results || []));
-	}
-
-	return results;
-}
-
-// Server/Data Center v1 content is reshaped to the Cloud v2 fields the formatters read.
-function serverSpace(space) {
-	return {
-		id: String(space.id),
-		key: space.key,
-		name: space.name,
-		type: space.type,
-		status: space.status,
-	};
-}
-
-function serverPage(page) {
-	return {
-		id: page.id,
-		title: page.title,
-		status: page.status,
-		spaceId: page.space?.id != null ? String(page.space.id) : undefined,
-		createdAt: page.history?.createdDate,
-		version: page.version ? { number: page.version.number } : undefined,
-		body: page.body,
-	};
-}
-
-// The content listing silently returns nothing for an unknown space key, so the space is looked up first.
-async function serverSpaceKey(conn, { spaceId, spaceKey }) {
-	if (!spaceKey) return (await listSpaces()).find((s) => s.id === String(spaceId))?.key;
-	try {
-		return (await request(conn, apiUrl(conn, `/rest/api/space/${encodeURIComponent(spaceKey)}`))).key;
-	} catch (err) {
-		if (err.status === 404) return undefined;
-		throw err;
-	}
-}
-
-export async function listSpaces() {
-	const conn = await connect();
-	if (conn.kind === 'cloud') return paginate(conn, '/api/v2/spaces');
-	return (await paginate(conn, '/rest/api/space', { limit: 100 })).map(serverSpace);
-}
-
-export async function getPage(id) {
-	const conn = await connect();
-	if (conn.kind === 'cloud') {
-		return request(conn, apiUrl(conn, `/api/v2/pages/${id}`), { 'body-format': 'storage' });
-	}
-	return serverPage(await request(conn, apiUrl(conn, `/rest/api/content/${id}`), {
-		expand: 'body.storage,version,space,history',
-	}));
-}
-
-// Cloud lists pages by space ID and Server/Data Center by space key; returns null for an unknown space.
-export async function listSpacePages({ spaceId, spaceKey }) {
-	const conn = await connect();
-	if (conn.kind === 'cloud') {
-		const id = spaceId
-			?? (await request(conn, apiUrl(conn, '/api/v2/spaces'), { keys: spaceKey })).results?.[0]?.id;
-		if (!id) return null;
-		return paginate(conn, `/api/v2/spaces/${id}/pages`);
-	}
-
-	const key = await serverSpaceKey(conn, { spaceId, spaceKey });
-	if (!key) return null;
-	const pages = await paginate(conn, '/rest/api/content', {
-		spaceKey: key,
-		type: 'page',
-		expand: 'version,history',
-		limit: 100,
-	});
-	return pages.map(serverPage);
-}
-
-export async function searchPages(cql) {
-	const conn = await connect();
-	const result = await request(conn, apiUrl(conn, '/rest/api/search'), { cql });
-	return { ...result, totalSize: result.totalSize ?? result.totalCount };
-}
+const deployments = new Map();
+
+// Custom domains hide the atlassian.net hostname, so anything else is probed:
+// Atlassian's edge answers tenant_info anonymously, Server/Data Center does not.
+async function detectDeployment(origin) {
+	if (/\.atlassian\.net$/i.test(new URL(origin).hostname)) return 'cloud';
+	try {
+		const res = await fetch(new URL('/_edge/tenant_info', origin), {
+			headers: { 'Accept': 'application/json' },
+		});
+		if (res.ok && (await res.json()).cloudId) return 'cloud';
+	} catch {
+		// An unreachable or non-JSON probe means no Atlassian edge; the real request reports connection errors.
+	}
+	return 'server';
+}
+
+async function connect({ baseUrl, email, token }) {
+	const base = new URL(baseUrl);
+	if (!deployments.has(base.origin)) deployments.set(base.origin, detectDeployment(base.origin));
+	const kind = await deployments.get(base.origin);
+	// Cloud always serves Confluence under /wiki; Server/Data Center keeps its own context path.
+	const path = kind === 'cloud' ? '/wiki' : base.pathname.replace(/\/+$/, '');
+	return { kind, origin: base.origin, path, email, token };
+}
+
+function apiUrl(conn, path) {
+	return new URL(`${conn.origin}${conn.path}${path}`);
+}
+
+// Cloud v2 links are origin-relative, Server/Data Center links are relative to the context path.
+function nextUrl(conn, link, current) {
+	const contextRelative = conn.kind === 'server'
+		&& link.startsWith('/') && !link.startsWith('//')
+		&& !(conn.path && link.startsWith(`${conn.path}/`));
+	return contextRelative ? apiUrl(conn, link) : new URL(link, current);
+}
+
+// Server/Data Center personal access tokens use Bearer auth; a username switches to Basic.
+function authHeader({ kind, email = '', token = '' }) {
+	if (kind === 'server' && !email) return `Bearer ${token}`;
+	return 'Basic ' + Buffer.from(`${email}:${token}`).toString('base64');
+}
+
+async function request(conn, url, params = {}) {
+	if (url.origin !== conn.origin) {
+		throw new Error('Confluence pagination points to a different site. Check the base URL of the Confluence connection.');
+	}
+	for (const [k, v] of Object.entries(params)) {
+		if (v !== undefined && v !== null) url.searchParams.set(k, v);
+	}
+
+	const res = await fetch(url, {
+		headers: {
+			'Authorization': authHeader(conn),
+			'Accept': 'application/json',
+		},
+	});
+
+	if (!res.ok) {
+		const err = new Error(`Confluence API error: ${res.status} ${res.statusText}`);
+		err.status = res.status;
+		err.url = url.toString();
+		throw err;
+	}
+
+	// Server/Data Center answers rejected credentials with a login page instead of a 401.
+	if (!res.headers.get('content-type')?.includes('json')) {
+		const err = new Error('Confluence returned a non-JSON response. Check the base URL and token of the Confluence connection.');
+		err.url = url.toString();
+		throw err;
+	}
+
+	return res.json();
+}
+
+async function paginate(conn, path, params = {}) {
+	const results = [];
+	let url = apiUrl(conn, path);
+	let data = await request(conn, url, params);
+	results.push(...(data.results || []));
+
+	while (data._links?.next) {
+		url = nextUrl(conn, data._links.next, url);
+		data = await request(conn, url);
+		results.push(...(data.results || []));
+	}
+
+	return results;
+}
+
+// Server/Data Center v1 content is reshaped to the Cloud v2 fields the formatters read.
+function serverSpace(space) {
+	return {
+		id: String(space.id),
+		key: space.key,
+		name: space.name,
+		type: space.type,
+		status: space.status,
+	};
+}
+
+function serverPage(page) {
+	return {
+		id: page.id,
+		title: page.title,
+		status: page.status,
+		spaceId: page.space?.id != null ? String(page.space.id) : undefined,
+		createdAt: page.history?.createdDate,
+		version: page.version ? { number: page.version.number } : undefined,
+		body: page.body,
+	};
+}
+
+// The content listing silently returns nothing for an unknown space key, so the space is looked up first.
+async function serverSpaceKey(conn, { spaceId, spaceKey }) {
+	if (!spaceKey) return (await spaces(conn)).find((s) => s.id === String(spaceId))?.key;
+	try {
+		return (await request(conn, apiUrl(conn, `/rest/api/space/${encodeURIComponent(spaceKey)}`))).key;
+	} catch (err) {
+		if (err.status === 404) return undefined;
+		throw err;
+	}
+}
+
+async function spaces(conn) {
+	if (conn.kind === 'cloud') return paginate(conn, '/api/v2/spaces');
+	return (await paginate(conn, '/rest/api/space', { limit: 100 })).map(serverSpace);
+}
+
+export async function listSpaces(connection) {
+	return spaces(await connect(connection));
+}
+
+export async function getPage(connection, id) {
+	const conn = await connect(connection);
+	if (conn.kind === 'cloud') {
+		return request(conn, apiUrl(conn, `/api/v2/pages/${id}`), { 'body-format': 'storage' });
+	}
+	return serverPage(await request(conn, apiUrl(conn, `/rest/api/content/${id}`), {
+		expand: 'body.storage,version,space,history',
+	}));
+}
+
+// Cloud lists pages by space ID and Server/Data Center by space key; returns null for an unknown space.
+export async function listSpacePages(connection, { spaceId, spaceKey }) {
+	const conn = await connect(connection);
+	if (conn.kind === 'cloud') {
+		const id = spaceId
+			?? (await request(conn, apiUrl(conn, '/api/v2/spaces'), { keys: spaceKey })).results?.[0]?.id;
+		if (!id) return null;
+		return paginate(conn, `/api/v2/spaces/${id}/pages`);
+	}
+
+	const key = await serverSpaceKey(conn, { spaceId, spaceKey });
+	if (!key) return null;
+	const pages = await paginate(conn, '/rest/api/content', {
+		spaceKey: key,
+		type: 'page',
+		expand: 'version,history',
+		limit: 100,
+	});
+	return pages.map(serverPage);
+}
+
+export async function searchPages(connection, cql) {
+	const conn = await connect(connection);
+	const result = await request(conn, apiUrl(conn, '/rest/api/search'), { cql });
+	return { ...result, totalSize: result.totalSize ?? result.totalCount };
+}

package/src/clients/graph-auth.js

@@ -0,0 +1,110 @@
+import { createHash } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { mkdir, rm } from 'node:fs/promises';
+import { configPath, validateGraphId } from '../config/store.js';
+import { createProtectedCache } from './graph-cache.js';
+
+export const GRAPH_SCOPES = ['User.Read', 'Chat.Read', 'Mail.Read', 'Sites.Read.All'];
+export const SHARED_MAIL_SCOPE = 'Mail.Read.Shared';
+export const CALENDAR_SCOPE = 'Calendars.Read.Shared';
+export const AVAILABILITY_SCOPE = 'Calendars.ReadBasic';
+
+function requestedScopes({ sharedMail = false, calendars = false, availability = false, all = false } = {}) {
+	return [...GRAPH_SCOPES,
+		...(sharedMail || all ? [SHARED_MAIL_SCOPE] : []),
+		...(calendars || all ? [CALENDAR_SCOPE, AVAILABILITY_SCOPE] : availability ? [AVAILABILITY_SCOPE] : []),
+	];
+}
+
+export function graphIdentity(connection = {}) {
+	const tenantId = connection.tenantId?.trim().toLowerCase();
+	const clientId = connection.clientId?.trim().toLowerCase();
+	if (validateGraphId(tenantId) || validateGraphId(clientId)) {
+		throw new Error('The Microsoft Graph connection needs a valid tenant ID and client ID. Run: dev graph setup');
+	}
+	return { tenantId, clientId };
+}
+
+// The token cache is partitioned by tenant and client ID, so connections for the same application share one sign-in.
+async function createApplication(connection) {
+	const { tenantId, clientId } = graphIdentity(connection);
+	const { PublicClientApplication } = await import('@azure/msal-node');
+	const identity = createHash('sha256').update(`${tenantId}:${clientId}`).digest('hex');
+	const directory = join(dirname(configPath()), 'graph-auth');
+	await mkdir(directory, { recursive: true, mode: 0o700 });
+	// Caches written by the earlier msal-node-extensions storage cannot be read by this one.
+	await rm(join(directory, `${identity}.bin`), { force: true });
+	await rm(join(directory, `${identity}.bin.lockfile`), { force: true });
+	return new PublicClientApplication({
+		auth: { clientId, authority: `https://login.microsoftonline.com/${tenantId}` },
+		cache: { cachePlugin: createProtectedCache({ path: join(directory, `${identity}.cache`), identity }) },
+	});
+}
+
+export function createGraphAuth({ connection, applicationFactory = () => createApplication(connection), browserOpener } = {}) {
+	let application;
+	const app = () => application ||= applicationFactory();
+
+	async function account() {
+		const accounts = await (await app()).getTokenCache().getAllAccounts();
+		if (accounts.length !== 1) throw new Error('Sign in to Microsoft Graph first. Run: dev graph login');
+		return accounts[0];
+	}
+
+	return {
+		async login(options = {}) {
+			const client = await app();
+			const openBrowser = browserOpener || (async (url) => {
+				const { default: open } = await import('open');
+				await open(url);
+			});
+			const scopes = requestedScopes(options);
+			const result = await client.acquireTokenInteractive({
+				scopes,
+				prompt: 'select_account',
+				openBrowser,
+				successTemplate: 'Return to the terminal to check the sign-in result. You can close this window.',
+				errorTemplate: 'Sign-in failed. Return to the terminal for details.',
+			});
+			if (!result?.account) throw new Error('Microsoft did not return an account. Run: dev graph login');
+			const cache = client.getTokenCache();
+			// A cache belongs to one CLI identity so silent requests never pick an arbitrary account.
+			for (const cached of await cache.getAllAccounts()) {
+				if (cached.homeAccountId !== result.account.homeAccountId) await cache.removeAccount(cached);
+			}
+			return { username: result.account.username, name: result.account.name || null, tenantId: result.account.tenantId };
+		},
+
+		async token({ sharedMail = false, calendars = false, availability = false } = {}) {
+			const client = await app();
+			const current = await account();
+			const scopes = requestedScopes({ sharedMail, calendars, availability });
+			try {
+				const result = await client.acquireTokenSilent({
+					account: current,
+					scopes,
+				});
+				if (!result?.accessToken) throw new Error('No access token returned.');
+				return result.accessToken;
+			} catch (err) {
+				if (['interaction_required', 'consent_required', 'login_required', 'invalid_grant', 'no_tokens_found'].includes(err.errorCode)
+					|| err.name === 'InteractionRequiredAuthError') {
+					const flags = `${sharedMail ? ' --shared-mail' : ''}${calendars || availability ? ' --calendars' : ''}`;
+					throw new Error(`Microsoft sign-in expired or needs consent for ${scopes.join(', ')}. Check delegated permissions, then run: dev graph login${flags}`);
+				}
+				throw err;
+			}
+		},
+
+		async status() {
+			const current = await account();
+			return { username: current.username, name: current.name || null, tenantId: current.tenantId, cached: true };
+		},
+
+		async logout() {
+			const cache = (await app()).getTokenCache();
+			for (const cached of await cache.getAllAccounts()) await cache.removeAccount(cached);
+			return { signedOut: true, message: 'Local Graph account removed. Browser sessions and server-side grants are unchanged.' };
+		},
+	};
+}

package/src/clients/graph-cache.js

@@ -0,0 +1,148 @@
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+import { open, readFile, rename, rm, stat } from 'node:fs/promises';
+
+const FORMAT = 1;
+const KEY_BYTES = 32;
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+const HEADER_BYTES = 1 + IV_BYTES + TAG_BYTES;
+
+function storeError(err) {
+	return new Error('Cannot open the OS credential store for the Graph token cache. Check your Windows account, macOS Keychain, or Linux Secret Service. Plaintext storage is disabled.', { cause: err });
+}
+
+// The OS store holds only the key: Windows Credential Manager limits a secret to about 2.5 KB, less than an MSAL cache.
+export async function keyringKeyStore(identity) {
+	const { AsyncEntry } = await import('@napi-rs/keyring');
+	// Linux would otherwise fall back to the kernel keyring, which loses the key at logout or reboot.
+	const entry = new AsyncEntry('devtool-graph-key', identity, { linux: { store: 'secret-service' } });
+	return {
+		async get() {
+			try {
+				const secret = await entry.getSecret();
+				return secret ? Buffer.from(secret) : null;
+			} catch (err) {
+				throw storeError(err);
+			}
+		},
+		async set(key) {
+			try {
+				await entry.setSecret(key);
+			} catch (err) {
+				throw storeError(err);
+			}
+		},
+	};
+}
+
+function fileLock(path, { timeout = 10000, stale = 30000, retry = 50 } = {}) {
+	let held = false;
+	return {
+		async acquire() {
+			const deadline = Date.now() + timeout;
+			for (;;) {
+				try {
+					await (await open(path, 'wx')).close();
+					held = true;
+					return;
+				} catch (err) {
+					if (err.code !== 'EEXIST') throw err;
+				}
+				// A process killed while holding the lock leaves the file behind.
+				const age = await stat(path).then((s) => Date.now() - s.mtimeMs, () => 0);
+				if (age > stale) await rm(path, { force: true });
+				else if (Date.now() > deadline) throw new Error('Timed out waiting for another devtool process to release the Graph token cache.');
+				else await new Promise((resolve) => setTimeout(resolve, retry));
+			}
+		},
+		async release() {
+			if (!held) return;
+			held = false;
+			await rm(path, { force: true });
+		},
+	};
+}
+
+/**
+ * MSAL cache plugin that stores the token cache AES-256-GCM encrypted in a file, keyed by a random
+ * key in the OS credential store. The identity is bound as associated data so files cannot be swapped.
+ */
+export function createProtectedCache({ path, identity, keyStore = () => keyringKeyStore(identity), lockOptions }) {
+	const lock = fileLock(`${path}.lock`, lockOptions);
+	const aad = Buffer.from(identity);
+	let store;
+	const keys = async () => (store ||= await keyStore());
+
+	async function readKey() {
+		const key = await (await keys()).get();
+		return key?.length === KEY_BYTES ? key : null;
+	}
+
+	// A missing key or a file that fails authentication is an empty cache: the user signs in again.
+	async function load() {
+		let file;
+		try {
+			file = await readFile(path);
+		} catch (err) {
+			if (err.code === 'ENOENT') return null;
+			throw err;
+		}
+		const key = await readKey();
+		if (!key || file.length < HEADER_BYTES || file[0] !== FORMAT) return null;
+		try {
+			const decipher = createDecipheriv('aes-256-gcm', key, file.subarray(1, 1 + IV_BYTES));
+			decipher.setAAD(aad);
+			decipher.setAuthTag(file.subarray(1 + IV_BYTES, HEADER_BYTES));
+			return Buffer.concat([decipher.update(file.subarray(HEADER_BYTES)), decipher.final()]).toString('utf8');
+		} catch {
+			return null;
+		}
+	}
+
+	async function save(data) {
+		let key = await readKey();
+		if (!key) {
+			key = randomBytes(KEY_BYTES);
+			await (await keys()).set(key);
+		}
+		const iv = randomBytes(IV_BYTES);
+		const cipher = createCipheriv('aes-256-gcm', key, iv);
+		cipher.setAAD(aad);
+		const body = Buffer.concat([cipher.update(data, 'utf8'), cipher.final()]);
+		const temporary = `${path}.${process.pid}.tmp`;
+		try {
+			const file = await open(temporary, 'w', 0o600);
+			try {
+				await file.writeFile(Buffer.concat([Buffer.from([FORMAT]), iv, cipher.getAuthTag(), body]));
+			} finally {
+				await file.close();
+			}
+			await rename(temporary, path);
+		} catch (err) {
+			await rm(temporary, { force: true });
+			throw err;
+		}
+	}
+
+	return {
+		// MSAL pairs every beforeCacheAccess with afterCacheAccess; the lock spans both when the cache will change.
+		async beforeCacheAccess(context) {
+			await lock.acquire();
+			try {
+				const data = await load();
+				if (data) context.tokenCache.deserialize(data);
+			} catch (err) {
+				await lock.release();
+				throw err;
+			}
+			if (!context.cacheHasChanged) await lock.release();
+		},
+		async afterCacheAccess(context) {
+			try {
+				if (context.cacheHasChanged) await save(context.tokenCache.serialize());
+			} finally {
+				await lock.release();
+			}
+		},
+	};
+}