@falldownthesystem/devtool 0.4.1 → 0.6.1

package/README.md

@@ -1,6 +1,6 @@
 # dev
 
-A terminal-first CLI for working with Bitbucket PRs, Jira tickets, and Confluence pages. Skip the browser, stay in your terminal.
+A terminal-first CLI for Bitbucket PRs, Jira tickets, Confluence pages, Service Desk tickets, and Microsoft Graph. Microsoft Graph provides read-only access to Teams chats, email, calendars, and SharePoint.
 
 ## Install
 
@@ -8,7 +8,7 @@ A terminal-first CLI for working with Bitbucket PRs, Jira tickets, and Confluenc
 npm install -g @falldownthesystem/devtool
 ```
 
-This gives you the `dev` command globally. On first run, it'll walk you through connecting your Bitbucket, Jira, and Confluence accounts.
+This gives you the `dev` command globally. Add a connection for each service you use with `dev config add`; services you don't use need no configuration.
 
 ## Usage
 
@@ -30,9 +30,13 @@ dev confluence view 12345    # read a page
 dev confluence pages         # pages in a space
 dev confluence search "auth" # CQL search
 
-dev config setup             # re-run setup
-dev config show              # current config (tokens masked)
-dev config set <key> <value> # set a single value
+dev config setup             # add or edit connections interactively
+dev config add jira -n work  # add a named Jira connection
+dev config edit work         # edit a connection interactively
+dev config remove work       # remove a connection
+dev config default work      # make it the default for its type
+dev config show              # all connections (tokens masked)
+dev config set <key> <value> # set a single field, e.g. work.baseUrl
 ```
 
 Most commands have short aliases: `ls`, `read`, `find`, `my`.
@@ -47,13 +51,167 @@ dev pr list --plain      # no colors, no tables, pipe-friendly
 dev pr list --json       # curated JSON, not raw API dumps
 ```
 
+### Multiple connections
+
+You can add any number of connections of each type. A connection's name is optional: an unnamed connection is referred to by its type (`jira`), and only one unnamed connection per type is allowed. Commands use the default connection of their type; pick another with `--connection`:
+
+```bash
+dev jira view PROJ-123                # default Jira connection
+dev jira view OPS-7 --connection work # the Jira connection named "work"
+dev confluence spaces -c wiki         # the Confluence connection named "wiki"
+```
+
+The default is the connection marked with `dev config default`, or otherwise the first connection of that type.
+
 ## Config
 
-Stored via the `conf` package in your OS config directory. You'll need:
+Stored via the `conf` package in your OS config directory. Each connection has a type and its own fields:
+
+- **bitbucket**: workspace, default repo, email, app password
+- **jira**: base URL, API token, default project
+- **confluence**: base URL, email, API token, default space. Cloud and Server/Data Center are detected from the base URL. For Server/Data Center, include any context path (`https://company.com/confluence`) and leave the email empty to use a personal access token, or set it to your username for Basic auth.
+- **serviceDesk**: base URL, email, API token, default project
+- **graph**: tenant ID, client ID, default SharePoint site (see [Microsoft Graph](#microsoft-graph))
+
+`dev config set <connection>.<field> <value>` addresses a connection by name or type, so the older keys such as `bitbucket.workspace` keep working. Configuration from earlier versions, with one section per service, is converted to unnamed connections on first run.
+
+## Microsoft Graph
+
+A Graph connection uses one application registration and one sign-in for all four services. No PAT or client secret is required. Graph commands do not require Bitbucket or Jira configuration. Like other connection types, you can add several Graph connections (for example one per tenant) and pick one with `--connection`.
+
+### Application registration and setup
+
+1. Register a single-tenant application in the [Microsoft Entra admin center](https://entra.microsoft.com).
+2. Under **Authentication**, add **Mobile and desktop applications** with redirect URI `http://localhost`.
+3. Add Microsoft Graph **delegated** permissions: `User.Read`, `Chat.Read`, `Mail.Read`, `Sites.Read.All`.
+4. Obtain administrator approval if your organization requires it.
+5. Run the Graph wizard, then sign in through your browser:
+
+```bash
+dev graph setup                  # edits the selected Graph connection, or adds one; also: dev config add graph
+dev graph login
+dev graph status                 # cached account only, not a token-validity check
+```
+
+The wizard asks for the **Directory (tenant) ID**, **Application (client) ID**, and an optional default SharePoint site URL. These IDs are not secrets. You can also set them individually:
+
+```bash
+dev config set graph.tenantId <tenant-uuid>
+dev config set graph.clientId <client-uuid>
+dev config set graph.defaultSite https://company.sharepoint.com/sites/MySite
+```
+
+`graph.<field>` addresses the default Graph connection; use `<name>.<field>` for a named one. Setup and login require an interactive terminal without `--json` or `--plain`. Data commands never prompt or open a browser. If sign-in expires or needs fresh consent, run `dev graph login` again.
+
+Tokens are kept in a cache file outside the repository, partitioned by tenant and client ID and encrypted with AES-256-GCM. The encryption key is stored in the OS credential store: Windows Credential Manager, macOS Keychain, or Linux Secret Service (required on Linux). There is no plaintext fallback. The credential store binding ships prebuilt for each platform, so installation needs no build tools or install scripts. `dev graph logout` removes the local cached account for the current tenant/client pair; it does not revoke grants or sign out browser sessions. Changing IDs selects another cache; log out before changing IDs if you want to remove the old account.
+
+For one sign-in covering every supported service, add the optional delegated permissions `Mail.Read.Shared`, `Calendars.Read.Shared`, and `Calendars.ReadBasic`, then run:
+
+```bash
+dev graph login --all
+```
+
+This is an alternative to the individual login flags, not an additional login step. The application name in the consent screen comes from your Entra registration. A permission marked **Admin consent required: No** can still require approval under your organization's user-consent policy. Changing authentication flows does not bypass that policy.
+
+### Teams chats
+
+```bash
+dev graph teams chats --limit 25
+dev graph teams view "<chat-id>"
+dev graph teams messages "<chat-id>" --limit 50
+dev graph teams message "<chat-id>" "<message-id>"
+```
+
+This covers your chats, not Teams channels. Expanded chat member lists can stop at 25 members.
+
+### Email
+
+```bash
+dev graph mail folders
+dev graph mail folders --parent "<folder-id>"
+dev graph mail list --folder inbox --limit 25
+dev graph mail search 'subject:release' --limit 50
+dev graph mail view "<message-id>"
+```
+
+`email` is an alias for `mail`. Reads do not mark messages as read. Search uses Microsoft's message search syntax and service-defined order, with a maximum of 1,000 matches. The CLI displays message bodies as text; it does not download email attachments.
+
+For shared mailboxes or another person's shared folders, add the **delegated** `Mail.Read.Shared` permission and sign in with that scope:
+
+```bash
+dev graph login --shared-mail
+dev graph mail --mailbox shared@company.com folders
+dev graph mail --mailbox shared@company.com list --folder inbox
+dev graph mail --mailbox owner@company.com view "<message-id>" --folder "<shared-folder-id>"
+```
+
+You also need Exchange access to the mailbox or folder. `Mail.Read` alone covers only your own mailbox. `--mailbox` accepts the mailbox owner's address or user ID; Graph does not discover your shared mailboxes. With folder-only access, specify that folder instead of requesting the entire mailbox. Normal commands do not request shared-mail permission.
+
+### Calendars
+
+Add the **delegated** `Calendars.Read.Shared` and `Calendars.ReadBasic` permissions, then sign in with `--calendars` (or `--all`). These cover calendar details and the free/busy query. Calendar details include your calendars and shared calendars you already have permission to read. It does not grant new Exchange access or allow event changes.
+
+```bash
+dev graph login --calendars
+dev graph login --calendars --shared-mail   # both optional permissions in one sign-in
+dev graph calendar list
+dev graph calendar next
+dev graph calendar events --limit 50
+dev graph calendar events --from 2026-09-14T00:00:00+03:00 --to 2026-09-21T00:00:00+03:00
+dev graph calendar --calendar "<calendar-id>" next
+dev graph calendar --mailbox owner@company.com --calendar "<calendar-id>" events
+dev graph calendar --calendar "<calendar-id>" view "<event-id>"
+```
+
+`calendars` aliases `calendar`. `list` returns calendars in the addressed mailbox, including shared calendars added there. Supply `--mailbox` to address the owner directly when needed. Calendar IDs belong to the mailbox context that returned them. The permission does not discover every calendar across the organization.
+
+`events`, `next`, and `view` use the primary calendar unless you supply `--calendar`; they do not merge all calendars. Event times use UTC. Date inputs require ISO 8601 with an explicit timezone. The default window starts now and ends 30 days later; custom windows can span up to 366 days. The client expands recurring meetings through `calendarView`, reads the complete window (up to 1,000 events), and sorts before selecting results. If the window exceeds 1,000 events, narrow the date range instead of accepting an unreliable next event.
+
+`next` finds the next appointment or meeting in the selected calendar. It excludes cancelled, declined, and already-started events. If no event qualifies, the result includes the checked date range. It does not change attendance, read status, or calendar contents.
+
+### Other users' free/busy times
+
+```bash
+dev graph calendar availability colleague@company.com
+dev graph calendar availability colleague@company.com room@company.com --from 2026-09-14T09:00:00+03:00 --to 2026-09-14T17:00:00+03:00 --interval 30
+```
+
+This calls Microsoft's read-only `getSchedule` query using `Calendars.ReadBasic`. It requires no event creation or attendance changes. Unlike full shared-calendar details, free/busy availability follows Exchange publishing and organization sharing policies. Private subjects and details may remain hidden.
+
+Supply 1–20 email addresses, not `--mailbox` or `--calendar`. The default range is now through 24 hours later. Custom ranges must be shorter than 62 days; intervals accept 5–1440 minutes. Results include UTC blocks and a compact slot string: `0` = free or working elsewhere, `1` = tentative, `2` = busy, `3` = out of office. Per-person errors remain visible and cause a nonzero exit status; missing or denied availability never means free. If Microsoft reports error `5006`, narrow the range or increase the interval.
+
+### SharePoint
+
+```bash
+dev graph sharepoint sites "Product"
+dev graph sharepoint site
+dev graph sharepoint --site https://company.sharepoint.com/sites/Other libraries
+dev graph sharepoint libraries
+dev graph sharepoint files "<drive-id>"
+dev graph sharepoint files "<drive-id>" --path "Product Data/Documentation/My Product"
+dev graph sharepoint files "<drive-id>" --folder "<folder-item-id>"
+dev graph sharepoint file "<drive-id>" "<item-id>"
+dev graph sharepoint download "<drive-id>" "<item-id>" "./document.pdf"
+dev graph sharepoint lists
+dev graph sharepoint items "<list-id>"
+dev graph sharepoint item "<list-id>" "<item-id>"
+```
+
+`sp` is an alias for `sharepoint`. Site-based commands use the connection's default site unless you supply `--site`. File commands use the explicit drive ID. Select the **Documents** library from `libraries`; `--path` starts inside that library, so omit the `Documents/` prefix. File downloads use a temporary file and expose the destination only after the transfer completes. An atomic hard link prevents overwriting a destination created concurrently; the destination filesystem must support hard links. Normal failures clean up temporary files. A forced process termination may leave a `.devtool-download-*` temporary directory, but never a partial destination. Each download request defaults to a 120-second timeout; use `--timeout <seconds>` (1–86400) for slower transfers. Other Graph requests have a 60-second timeout. The download changes no remote data and sends no Graph bearer token to the SharePoint download host.
+
+### Output and limits
+
+All Graph data commands support rich tables, `--plain`, and curated `--json`. Collection commands default to 25 results; `--limit` accepts 1–1000. The client follows server pagination up to that limit, so more results can exist. JSON lists are arrays. Errors go to stderr with a nonzero exit status; `--json` errors use `{"error":{"message":"...","status":403}}`. Authentication tokens, raw Graph metadata, and preauthenticated file download URLs never appear in curated output.
+
+Content reads use GET. The only POST is the fixed `/me/calendar/getSchedule` endpoint, which computes free/busy information without changing data. The CLI has no Graph mail-send, message-send, upload, update, or delete commands.
+
+## Development
+
+```bash
+npm test
+```
 
-- **Bitbucket**: workspace, default repo, email, app password
-- **Jira**: base URL, API token, default project
-- **Confluence**: uses the same Jira base URL and token
+The Node.js test suite uses mock Graph and authentication responses, temporary configuration, and local download fixtures. It does not access Microsoft 365 data.
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@falldownthesystem/devtool",
-	"version": "0.4.1",
-	"description": "CLI for Bitbucket PRs, Jira tickets, Confluence pages, and Service Desk tickets",
+	"version": "0.6.1",
+	"description": "CLI for Bitbucket, Jira, Confluence, Service Desk, and Microsoft Graph",
 	"type": "module",
 	"bin": {
 		"dev": "src/index.js"
@@ -11,7 +11,7 @@
 	],
 	"scripts": {
 		"start": "node src/index.js",
-		"test": "node --test test/config.test.js test/confluence.test.js test/service-desk.test.js"
+		"test": "node --test test/config.test.js test/confluence.test.js test/service-desk.test.js test/graph.test.js"
 	},
 	"keywords": [
 		"cli",
@@ -31,11 +31,15 @@
 		"node": ">=18"
 	},
 	"dependencies": {
+		"@azure/msal-node": "^6.0.0",
 		"@clack/prompts": "^1.0.0",
+		"@napi-rs/keyring": "^2.1.2",
 		"cli-table3": "^0.6.5",
 		"commander": "^14.0.3",
 		"conf": "^15.1.0",
+		"html-to-text": "^10.0.1",
 		"jira.js": "^5.3.0",
+		"open": "^11.0.3",
 		"picocolors": "^1.1.1"
 	}
 }

package/src/clients/bitbucket.js

@@ -1,20 +1,16 @@
-import { get } from '../config/store.js';
-
 const BASE_URL = 'https://api.bitbucket.org/2.0';
 
-function authHeader() {
-	const email = get('bitbucket.email');
-	const token = get('bitbucket.token');
-	return 'Basic ' + Buffer.from(`${email}:${token}`).toString('base64');
+function authHeader(connection) {
+	return 'Basic ' + Buffer.from(`${connection.email}:${connection.token}`).toString('base64');
 }
 
-function repoPath(repoOverride) {
-	const workspace = get('bitbucket.workspace');
-	const repo = repoOverride || get('bitbucket.defaultRepo');
-	return `/repositories/${workspace}/${repo}`;
+function repoPath(connection, repoOverride) {
+	const repo = repoOverride || connection.defaultRepo;
+	if (!repo) throw new Error('No repository specified. Pass --repo <slug> or set defaultRepo on the Bitbucket connection.');
+	return `/repositories/${connection.workspace}/${repo}`;
 }
 
-async function request(path, params = {}) {
+async function request(connection, path, params = {}) {
 	const url = new URL(path.startsWith('http') ? path : `${BASE_URL}${path}`);
 	for (const [k, v] of Object.entries(params)) {
 		if (v !== undefined && v !== null) url.searchParams.set(k, v);
@@ -22,7 +18,7 @@ async function request(path, params = {}) {
 
 	const res = await fetch(url, {
 		headers: {
-			'Authorization': authHeader(),
+			'Authorization': authHeader(connection),
 			'Accept': 'application/json',
 		},
 	});
@@ -37,25 +33,25 @@ async function request(path, params = {}) {
 	return res.json();
 }
 
-async function paginate(path, params = {}) {
+async function paginate(connection, path, params = {}) {
 	const results = [];
-	let data = await request(path, params);
+	let data = await request(connection, path, params);
 	results.push(...(data.values || []));
 
 	while (data.next) {
-		data = await request(data.next);
+		data = await request(connection, data.next);
 		results.push(...(data.values || []));
 	}
 
 	return results;
 }
 
-export async function listPullRequests(options = {}) {
+export async function listPullRequests(connection, options = {}) {
 	const { state = 'OPEN', author, repo } = options;
-	const path = `${repoPath(repo)}/pullrequests`;
+	const path = `${repoPath(connection, repo)}/pullrequests`;
 	const params = { state, pagelen: 50 };
 
-	const prs = await paginate(path, params);
+	const prs = await paginate(connection, path, params);
 
 	if (author) {
 		const authorLower = author.toLowerCase();
@@ -68,18 +64,18 @@ export async function listPullRequests(options = {}) {
 	return prs;
 }
 
-export async function getPullRequest(id, repo) {
-	return request(`${repoPath(repo)}/pullrequests/${id}`);
+export async function getPullRequest(connection, id, repo) {
+	return request(connection, `${repoPath(connection, repo)}/pullrequests/${id}`);
 }
 
-export async function getPullRequestComments(id, repo) {
-	return paginate(`${repoPath(repo)}/pullrequests/${id}/comments`);
+export async function getPullRequestComments(connection, id, repo) {
+	return paginate(connection, `${repoPath(connection, repo)}/pullrequests/${id}/comments`);
 }
 
-export async function getPullRequestDiffstat(id, repo) {
-	return paginate(`${repoPath(repo)}/pullrequests/${id}/diffstat`);
+export async function getPullRequestDiffstat(connection, id, repo) {
+	return paginate(connection, `${repoPath(connection, repo)}/pullrequests/${id}/diffstat`);
 }
 
-export async function getPullRequestActivity(id, repo) {
-	return paginate(`${repoPath(repo)}/pullrequests/${id}/activity`);
+export async function getPullRequestActivity(connection, id, repo) {
+	return paginate(connection, `${repoPath(connection, repo)}/pullrequests/${id}/activity`);
 }

package/src/clients/confluence.js

@@ -1,18 +1,50 @@
-import { get } from '../config/store.js';
+const deployments = new Map();
 
-function apiUrl(path) {
-	return new URL(`/wiki${path}`, get('confluence.baseUrl'));
+// 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);
 }
 
-function authHeader() {
-	const email = get('confluence.email');
-	const token = get('confluence.token');
+// 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(url, params = {}) {
-	if (url.origin !== new URL(get('confluence.baseUrl')).origin) {
-		throw new Error('Confluence pagination points to a different site. Check confluence.baseUrl.');
+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);
@@ -20,7 +52,7 @@ async function request(url, params = {}) {
 
 	const res = await fetch(url, {
 		headers: {
-			'Authorization': authHeader(),
+			'Authorization': authHeader(conn),
 			'Accept': 'application/json',
 		},
 	});
@@ -32,36 +64,107 @@ async function request(url, params = {}) {
 		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 paginateV2(path, params = {}) {
+async function paginate(conn, path, params = {}) {
 	const results = [];
-	let url = apiUrl(path);
-	let data = await request(url, params);
+	let url = apiUrl(conn, path);
+	let data = await request(conn, url, params);
 	results.push(...(data.results || []));
 
 	while (data._links?.next) {
-		url = new URL(data._links.next, url);
-		data = await request(url);
+		url = nextUrl(conn, data._links.next, url);
+		data = await request(conn, url);
 		results.push(...(data.results || []));
 	}
 
 	return results;
 }
 
-export async function listSpaces() {
-	return paginateV2('/api/v2/spaces');
+// 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,
+	};
 }
 
-export async function getPage(id) {
-	return request(apiUrl(`/api/v2/pages/${id}`), { 'body-format': 'storage' });
+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,
+	};
 }
 
-export async function listSpacePages(spaceId) {
-	return paginateV2(`/api/v2/spaces/${spaceId}/pages`);
+// 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(cql) {
-	return request(apiUrl('/rest/api/search'), { cql });
+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.' };
+		},
+	};
+}