@bettercms-ai/device-auth

OAuth 2.0 Device Authorization Grant (RFC 8628) against BetterCMS, plus the credential store and the browser opener that go with it. Zero runtime dependencies.

Used by @bettercms-ai/mcp (the MCP server) and @bettercms-ai/cli. It is a building block, not a product — install one of those instead unless you are writing another BetterCMS client.

import { DeviceAuthClient, FileTokenStore, loadConfig, openBrowser } from "@bettercms-ai/device-auth";

const config = loadConfig({ credentialsFile: "my-credentials.json", clientName: "My Client" });
const store = new FileTokenStore(config.credentialsPath, config.apiUrl);
const auth = new DeviceAuthClient(config, store);

const token = await auth.getAccessToken(); // may throw DeviceAuthPendingError first

getAccessToken() returns a cached token, refreshes an expired one, or runs the device flow. While the user has not approved yet it throws DeviceAuthPendingError, which carries the verification link to show them (openBrowser it, and print it as the fallback); call again to resume. A denied or expired code throws DeviceAuthError.

Environment: BETTERCMS_API_URL, BETTERCMS_MCP_CREDENTIALS, BETTERCMS_MCP_CLIENT_NAME.