@motorical/mcp 1.1.3 → 1.2.0

package/README.md

@@ -25,6 +25,39 @@ A **Motorical SMTP Motor Block** is an isolated sending stream (similar to a per
 
 Safety: real sends require `dryRun: false` **and** `confirmRealSend: true`. Sandbox outbound is allowlist-locked until convert. Optional `fromName` sets the inbox display name (same as HTTP `/v1/send` / CLI `--from-name`); do not put `From` in custom headers.
 
+## Authorization (recommended)
+
+Sign in once; no keys to paste, copy, or rotate by hand:
+
+```bash
+npx @motorical/mcp login
+```
+
+This opens your browser, you approve the scopes on Motorical's consent screen,
+and the grant is stored at `~/.motorical/mcp-credentials.json` (owner-only,
+`0600`). Access tokens last an hour and refresh silently.
+
+- `motorical-mcp status` — show the current connection
+
+An authorization covers **every Motor Block you own**, so block-scoped calls
+must say which one they mean. Set `MOTORICAL_MOTOR_BLOCK_ID` (or pass
+`motorBlockId` per call); the tools fail with a clear message rather than a bare
+API error if it is missing.
+- `motorical-mcp logout` — remove the local credentials
+
+Logging out only deletes the local file. To cut the agent's access off at the
+server, revoke the connection in **Settings → API Access → Connected AI
+Agents**; that takes effect immediately, on every device, and does not sign you
+out of your own dashboard.
+
+Under the hood this is OAuth 2.1: PKCE `S256`, a loopback redirect, RFC 8707
+audience-bound tokens, and RFC 9207 issuer checking on the callback. The client
+is public, so refresh tokens rotate on every use.
+
+The environment variables below still work and are the right choice for CI or a
+headless server, where no browser is available. When an OAuth session is present
+it takes precedence over them.
+
 ## Environment
 
 | Variable | Required | Description |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@motorical/mcp",
-  "version": "1.1.3",
-  "description": "MCP server for Motorical transactional email API — dry-run/send, mint public tokens, list Motor Blocks, inspect delivery events",
+  "version": "1.2.0",
+  "description": "MCP server for Motorical transactional email API \u2014 dry-run/send, mint public tokens, list Motor Blocks, inspect delivery events",
   "type": "module",
   "bin": {
     "motorical-mcp": "./src/index.js"
@@ -42,7 +42,7 @@
   },
   "homepage": "https://docs.motorical.com/ai-mcp",
   "bugs": {
-    "url": "https://github.com/motorical-smtp/motorical-packages/issues"
+    "url": "https://github.com/motorical-smtp/motorical-backend/issues"
   },
   "repository": {
     "type": "git",

package/src/client.js

@@ -3,6 +3,10 @@
  * Auth rules match docs.motorical.com (mk_live_ → /v1/send; ak_live_ → mint bearer).
  */
 
+import {
+  loadCredentials, saveCredentials, isExpired, discover, refreshTokens,
+} from './oauth.js';
+
 const DEFAULT_API_BASE = 'https://api.motorical.com';
 const DEFAULT_DOCS_BASE = 'https://docs.motorical.com';
 
@@ -15,7 +19,9 @@ export function loadConfig(env = process.env) {
     bearerToken: env.MOTORICAL_BEARER_TOKEN || '',
     dashboardJwt: env.MOTORICAL_JWT || '',
     motorBlockId: env.MOTORICAL_MOTOR_BLOCK_ID || '',
-    defaultFrom: env.MOTORICAL_DEFAULT_FROM || ''
+    defaultFrom: env.MOTORICAL_DEFAULT_FROM || '',
+    // A grant from `motorical-mcp login`, when one exists.
+    oauthCredentials: loadCredentials()
   };
 }
 
@@ -26,12 +32,56 @@ export class MotoricalClient {
     this._cachedBearer = config.bearerToken || null;
     /** @type {string|null} */
     this._cachedMkKey = null;
+    /**
+     * An OAuth grant from `motorical-mcp login`. When present it is preferred
+     * over pasted keys: it is scoped, revocable from the dashboard, and expires.
+     */
+    // Read ONLY from config. An implicit loadCredentials() here would make the
+    // client behave differently on a machine that happens to have logged in —
+    // including inside tests. loadConfig() is the one place the disk is read.
+    this._oauth = config.oauthCredentials || null;
+    this._oauthMeta = null;
+  }
+
+  hasOAuthSession() {
+    return !!(this._oauth && this._oauth.accessToken);
+  }
+
+  /** Returns a live OAuth access token, refreshing (and rotating) if needed. */
+  async oauthAccessToken({ fetchImpl } = {}) {
+    if (!this.hasOAuthSession()) return null;
+    if (!isExpired(this._oauth)) return this._oauth.accessToken;
+
+    if (!this._oauth.refreshToken) {
+      throw new Error('Motorical session expired and has no refresh token. Run: motorical-mcp login');
+    }
+    if (!this._oauthMeta) {
+      this._oauthMeta = await discover(this._oauth.issuer, fetchImpl || fetch);
+    }
+    let tokens;
+    try {
+      tokens = await refreshTokens(this._oauthMeta, { refreshToken: this._oauth.refreshToken }, fetchImpl || fetch);
+    } catch (err) {
+      throw new Error(`Motorical session could not be refreshed (${err.message}). Run: motorical-mcp login`);
+    }
+    this._oauth = {
+      ...this._oauth,
+      accessToken: tokens.access_token,
+      // Rotation is mandatory for public clients: the old refresh token is dead.
+      refreshToken: tokens.refresh_token || this._oauth.refreshToken,
+      scope: tokens.scope || this._oauth.scope,
+      expiresAt: Date.now() + (Number(tokens.expires_in || 3600) * 1000),
+    };
+    try { saveCredentials(this._oauth); } catch { /* keep working in-memory */ }
+    return this._oauth.accessToken;
   }
 
   requireMk() {
     if (this._cachedMkKey) return this._cachedMkKey;
     if (!this.config.mkApiKey) {
-      throw new Error('MOTORICAL_MK_API_KEY is required (mk_live_... Motor Block API key for POST /v1/send)');
+      throw new Error(
+        'No credentials for sending. Run `motorical-mcp login`, or set MOTORICAL_MK_API_KEY (mk_live_...).'
+      );
     }
     return this.config.mkApiKey;
   }
@@ -96,7 +146,32 @@ export class MotoricalClient {
     return data;
   }
 
+  /**
+   * An OAuth grant covers every Motor Block the user owned at consent time, so
+   * a block-scoped request must say which one it means. (A minted public token
+   * carried a single block inside the token, so this never came up before.)
+   * Fails here with an actionable message rather than letting the API answer
+   * with a bare 400.
+   */
+  _scoped(path, motorBlockId) {
+    if (!this.hasOAuthSession()) return path;
+    const id = motorBlockId || this.config.motorBlockId;
+    if (!id) {
+      throw new Error(
+        'motorBlockId is required: your Motorical authorization covers multiple Motor Blocks. '
+        + 'Pass motorBlockId, or set MOTORICAL_MOTOR_BLOCK_ID.'
+      );
+    }
+    const sep = path.includes('?') ? '&' : '?';
+    return `${path}${sep}motorBlockId=${encodeURIComponent(id)}`;
+  }
+
   async getBearer({ motorBlockId, forceRefresh = false } = {}) {
+    // An OAuth grant supersedes minted public tokens entirely — no ak_live_ key
+    // and no dashboard JWT needed.
+    const oauthToken = await this.oauthAccessToken();
+    if (oauthToken) return oauthToken;
+
     if (this._cachedBearer && !forceRefresh) return this._cachedBearer;
     const minted = await this.mintPublicToken({ motorBlockId });
     const token = minted?.data?.token || minted?.token || minted?.access_token;
@@ -107,7 +182,7 @@ export class MotoricalClient {
 
   async listMotorBlocks({ motorBlockId } = {}) {
     const bearer = await this.getBearer({ motorBlockId });
-    return this.request('GET', '/api/public/v1/motor-blocks', { bearer });
+    return this.request('GET', this._scoped('/api/public/v1/motor-blocks', motorBlockId), { bearer });
   }
 
   async sendEmail(payload) {
@@ -140,8 +215,25 @@ export class MotoricalClient {
     const headers = {};
     if (idempotencyKey) headers['Idempotency-Key'] = idempotencyKey;
 
-    return this.request('POST', '/v1/send', {
-      apiKey: this.requireMk(),
+    const oauthToken = await this.oauthAccessToken();
+    if (oauthToken && !this.config.motorBlockId && !payload.motorBlockId) {
+      throw new Error(
+        'motorBlockId is required to send with an OAuth authorization: it covers every Motor Block '
+        + 'you own. Set MOTORICAL_MOTOR_BLOCK_ID, or pass motorBlockId.'
+      );
+    }
+    const auth = oauthToken ? { bearer: oauthToken } : { apiKey: this.requireMk() };
+
+    // The block goes in the query string, not the body: /v1/send validates its
+    // body strictly and rejects unknown keys, and an api-key client's block
+    // comes from the key itself — a body field that disagreed would be a
+    // silent footgun.
+    const sendPath = oauthToken
+      ? `/v1/send?motorBlockId=${encodeURIComponent(payload.motorBlockId || this.config.motorBlockId)}`
+      : '/v1/send';
+
+    return this.request('POST', sendPath, {
+      ...auth,
       headers,
       body: {
         from: fromAddr,
@@ -161,14 +253,14 @@ export class MotoricalClient {
     if (!messageId) throw new Error('messageId is required');
     const bearer = await this.getBearer({ motorBlockId });
     const q = includePII ? '?includePII=true' : '';
-    return this.request('GET', `/api/public/v1/messages/${encodeURIComponent(messageId)}${q}`, { bearer });
+    return this.request('GET', this._scoped(`/api/public/v1/messages/${encodeURIComponent(messageId)}${q}`, motorBlockId), { bearer });
   }
 
   async getMessageEvents(messageId, { includePII = false, motorBlockId } = {}) {
     if (!messageId) throw new Error('messageId is required');
     const bearer = await this.getBearer({ motorBlockId });
     const q = includePII ? '?includePII=true' : '';
-    return this.request('GET', `/api/public/v1/messages/${encodeURIComponent(messageId)}/events${q}`, { bearer });
+    return this.request('GET', this._scoped(`/api/public/v1/messages/${encodeURIComponent(messageId)}/events${q}`, motorBlockId), { bearer });
   }
 
   async getSendApiStatus() {
@@ -219,6 +311,16 @@ export class MotoricalClient {
   }
 
   async domainList() {
+    // An OAuth grant reads the scoped public endpoint. It cannot use
+    // /api/domains: that route is behind the dashboard-session middleware,
+    // which also guards billing and account settings.
+    const oauthToken = await this.oauthAccessToken();
+    if (oauthToken) {
+      // Domains are account-wide, but authenticatePublic keeps MCP grants
+      // strictly block-bound rather than silently choosing one, so the
+      // selector travels here too. The endpoint scopes by user, not by block.
+      return this.request('GET', this._scoped('/api/public/v1/domains'), { bearer: oauthToken });
+    }
     return this.request('GET', '/api/domains', {
       bearer: this.requireDashboardJwt()
     });

package/src/index.js

@@ -1,13 +1,38 @@
 #!/usr/bin/env node
 /**
  * Motorical MCP server — stdio transport for Cursor / Claude Desktop / etc.
- * Credentials via env (see README). Log only to stderr.
+ * Auth: `motorical-mcp login` (OAuth 2.1), or env credentials (see README).
+ * Log only to stderr — stdout is the MCP stream.
  */
 
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createMotoricalMcpServer } from './server.js';
 
+const USAGE = `motorical-mcp — Motorical MCP server
+
+  motorical-mcp             start the MCP server on stdio (default)
+  motorical-mcp login       authorize with Motorical in your browser
+  motorical-mcp logout      revoke the authorization and remove local credentials
+                            (--local-only to forget it without revoking)
+  motorical-mcp status      show the current connection
+`;
+
 async function main() {
+  const cmd = process.argv[2];
+
+  if (cmd === 'login' || cmd === 'logout' || cmd === 'status') {
+    const mod = await import('./login.js');
+    if (cmd === 'login') await mod.login();
+    if (cmd === 'logout') await mod.logout({ revoke: !process.argv.includes('--local-only') });
+    if (cmd === 'status') mod.status();
+    return;
+  }
+
+  if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
+    console.error(USAGE);
+    return;
+  }
+
   const { server } = createMotoricalMcpServer();
   const transport = new StdioServerTransport();
   await server.connect(transport);
@@ -15,6 +40,6 @@ async function main() {
 }
 
 main().catch((err) => {
-  console.error('[motorical-mcp] fatal:', err);
+  console.error('[motorical-mcp] fatal:', err.message || err);
   process.exit(1);
 });

package/src/login.js

@@ -0,0 +1,105 @@
+/**
+ * `motorical-mcp login` — interactive OAuth 2.1 authorization.
+ * Everything it prints goes to stderr so it never corrupts an stdio MCP stream.
+ */
+
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
+import {
+  DEFAULT_ISSUER, DEFAULT_RESOURCE,
+  discover, generatePkce, buildAuthorizeUrl, startCallbackServer,
+  exchangeCode, toStoredCredentials, saveCredentials, clearCredentials, revokeToken,
+  credentialsPath, loadCredentials,
+} from './oauth.js';
+
+const DEFAULT_SCOPES = ['send:transactional', 'read:analytics', 'manage:domains'];
+
+function openBrowser(url) {
+  const cmd = process.platform === 'darwin' ? 'open'
+    : process.platform === 'win32' ? 'start' : 'xdg-open';
+  try {
+    spawn(cmd, [url], { stdio: 'ignore', detached: true, shell: process.platform === 'win32' }).unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function login({
+  issuer = process.env.MOTORICAL_ISSUER || DEFAULT_ISSUER,
+  resource = process.env.MOTORICAL_RESOURCE || DEFAULT_RESOURCE,
+  scopes = DEFAULT_SCOPES,
+  open = true,
+  log = (m) => console.error(m),
+} = {}) {
+  const meta = await discover(issuer);
+  const { verifier, challenge } = generatePkce();
+  const state = crypto.randomBytes(16).toString('base64url');
+
+  const server = await startCallbackServer({ expectedState: state, expectedIssuer: issuer });
+  const authorizeUrl = buildAuthorizeUrl(meta, {
+    redirectUri: server.redirectUri, challenge, state, scopes, resource,
+  });
+
+  log('');
+  log('Authorize Motorical in your browser:');
+  log(`  ${authorizeUrl}`);
+  log('');
+  if (open && !openBrowser(authorizeUrl)) {
+    log('(could not open a browser automatically — copy the link above)');
+  }
+
+  let code;
+  try {
+    code = await server.waitForCode;
+  } catch (err) {
+    server.close();
+    throw err;
+  }
+
+  const tokens = await exchangeCode(meta, {
+    code, verifier, redirectUri: server.redirectUri, resource,
+  });
+  const creds = toStoredCredentials(tokens, { issuer, resource });
+  const file = saveCredentials(creds);
+
+  log(`Connected. Credentials stored at ${file} (owner-only).`);
+  log(`Scopes granted: ${creds.scope || scopes.join(' ')}`);
+  return creds;
+}
+
+export async function logout({ log = (m) => console.error(m), revoke = true } = {}) {
+  const creds = loadCredentials();
+  if (!creds) { log('No stored credentials to remove.'); return false; }
+
+  if (revoke) {
+    try {
+      const meta = await discover(creds.issuer);
+      const ok = await revokeToken(meta, {
+        token: creds.refreshToken || creds.accessToken,
+        tokenTypeHint: creds.refreshToken ? 'refresh_token' : 'access_token',
+      });
+      log(ok
+        ? 'Revoked the authorization on the server.'
+        : 'Could not revoke on the server — revoke it in Settings → API Access.');
+    } catch (err) {
+      log(`Could not reach the server to revoke (${err.message}).`);
+      log('The grant is still live — revoke it in Settings → API Access.');
+    }
+  }
+
+  const removed = clearCredentials();
+  log(removed ? `Removed ${credentialsPath()}.` : 'No local credentials file to remove.');
+  return removed;
+}
+
+export function status({ log = (m) => console.error(m) } = {}) {
+  const creds = loadCredentials();
+  if (!creds) { log('Not connected. Run: motorical-mcp login'); return null; }
+  log(`Connected to ${creds.issuer}`);
+  log(`  resource: ${creds.resource}`);
+  log(`  scopes:   ${creds.scope || '(unknown)'}`);
+  log(`  expires:  ${new Date(creds.expiresAt).toISOString()}`);
+  log(`  file:     ${credentialsPath()}`);
+  return creds;
+}

package/src/oauth.js

@@ -0,0 +1,235 @@
+/**
+ * OAuth 2.1 + PKCE login for the Motorical MCP server.
+ *
+ * Replaces pasted mk_live_/ak_live_ keys: the user authorizes once in a
+ * browser and the resulting grant is stored locally and refreshed silently.
+ * The client is public (no secret), so PKCE S256 and refresh rotation are
+ * mandatory rather than optional.
+ */
+
+import http from 'node:http';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+export const DEFAULT_ISSUER = 'https://motorical.com';
+export const DEFAULT_RESOURCE = 'https://api.motorical.com';
+export const CLIENT_ID = 'https://motorical.com/.well-known/motorical-mcp-client.json';
+
+const CREDENTIALS_DIR = path.join(os.homedir(), '.motorical');
+const CREDENTIALS_FILE = path.join(CREDENTIALS_DIR, 'mcp-credentials.json');
+
+/** Tokens are user credentials: owner-only, never world-readable. */
+export function saveCredentials(creds, file = CREDENTIALS_FILE) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(file, JSON.stringify(creds, null, 2), { mode: 0o600 });
+  try { fs.chmodSync(file, 0o600); } catch { /* best effort on odd filesystems */ }
+  return file;
+}
+
+export function loadCredentials(file = CREDENTIALS_FILE) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function clearCredentials(file = CREDENTIALS_FILE) {
+  try { fs.unlinkSync(file); return true; } catch { return false; }
+}
+
+export function credentialsPath() { return CREDENTIALS_FILE; }
+
+export function generatePkce() {
+  const verifier = crypto.randomBytes(32).toString('base64url');
+  const challenge = crypto.createHash('sha256').update(verifier).digest('base64url');
+  return { verifier, challenge };
+}
+
+/** RFC 8414 discovery, so endpoints are never hardcoded past the issuer. */
+export async function discover(issuer = DEFAULT_ISSUER, fetchImpl = fetch) {
+  const res = await fetchImpl(`${issuer}/.well-known/oauth-authorization-server`, {
+    headers: { Accept: 'application/json' },
+  });
+  if (!res.ok) throw new Error(`Discovery failed: HTTP ${res.status}`);
+  const meta = await res.json();
+  if (meta.issuer !== issuer) {
+    throw new Error(`Issuer mismatch: document says ${meta.issuer}, expected ${issuer}`);
+  }
+  // A client MUST refuse to continue without PKCE S256 support.
+  if (!Array.isArray(meta.code_challenge_methods_supported)
+      || !meta.code_challenge_methods_supported.includes('S256')) {
+    throw new Error('Authorization server does not advertise PKCE S256 — refusing to continue');
+  }
+  return meta;
+}
+
+export function buildAuthorizeUrl(meta, { redirectUri, challenge, state, scopes, resource }) {
+  const u = new URL(meta.authorization_endpoint);
+  u.searchParams.set('client_id', CLIENT_ID);
+  u.searchParams.set('response_type', 'code');
+  u.searchParams.set('redirect_uri', redirectUri);
+  u.searchParams.set('scope', scopes.join(' '));
+  u.searchParams.set('state', state);
+  u.searchParams.set('code_challenge', challenge);
+  u.searchParams.set('code_challenge_method', 'S256');
+  u.searchParams.set('resource', resource);
+  return u.toString();
+}
+
+/**
+ * RFC 9207: the callback carries `iss`. Comparing it to the issuer we
+ * discovered is what stops a mix-up attack, where a malicious AS relays the
+ * user to a different one and harvests the code.
+ */
+export function validateCallback({ params, expectedState, expectedIssuer }) {
+  if (params.get('error')) {
+    throw new Error(params.get('error_description') || params.get('error'));
+  }
+  if (params.get('state') !== expectedState) {
+    throw new Error('State mismatch — discarding this callback');
+  }
+  const iss = params.get('iss');
+  if (iss && iss !== expectedIssuer) {
+    throw new Error(`Issuer mismatch in callback: ${iss}`);
+  }
+  const code = params.get('code');
+  if (!code) throw new Error('Authorization callback carried no code');
+  return code;
+}
+
+export async function exchangeCode(meta, { code, verifier, redirectUri, resource }, fetchImpl = fetch) {
+  const body = new URLSearchParams({
+    grant_type: 'authorization_code',
+    code,
+    client_id: CLIENT_ID,
+    redirect_uri: redirectUri,
+    code_verifier: verifier,
+    resource,
+  });
+  const res = await fetchImpl(meta.token_endpoint, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+    body: body.toString(),
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(data.error_description || data.error || `Token exchange failed: HTTP ${res.status}`);
+  return data;
+}
+
+export async function refreshTokens(meta, { refreshToken }, fetchImpl = fetch) {
+  const body = new URLSearchParams({
+    grant_type: 'refresh_token',
+    refresh_token: refreshToken,
+    client_id: CLIENT_ID,
+  });
+  const res = await fetchImpl(meta.token_endpoint, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+    body: body.toString(),
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(data.error_description || data.error || `Refresh failed: HTTP ${res.status}`);
+  return data;
+}
+
+/**
+ * RFC 7009. Deleting the local file leaves the grant alive on the server —
+ * still valid, still refreshable, belonging to nobody. "Log out" should mean
+ * the access is gone, so revoke before forgetting.
+ */
+export async function revokeToken(meta, { token, tokenTypeHint = 'refresh_token' }, fetchImpl = fetch) {
+  if (!meta?.revocation_endpoint) return false;
+  const body = new URLSearchParams({
+    token, token_type_hint: tokenTypeHint, client_id: CLIENT_ID,
+  });
+  const res = await fetchImpl(meta.revocation_endpoint, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: body.toString(),
+  });
+  return res.ok;
+}
+
+/** Shape stored on disk; `expiresAt` is absolute so a stale clock is obvious. */
+export function toStoredCredentials(tokenResponse, { issuer, resource }) {
+  return {
+    version: 1,
+    issuer,
+    resource,
+    accessToken: tokenResponse.access_token,
+    refreshToken: tokenResponse.refresh_token || null,
+    scope: tokenResponse.scope || '',
+    expiresAt: Date.now() + (Number(tokenResponse.expires_in || 3600) * 1000),
+    obtainedAt: Date.now(),
+  };
+}
+
+/** 60s skew so a token is never used in the instant before it expires. */
+export function isExpired(creds, now = Date.now()) {
+  if (!creds?.expiresAt) return true;
+  return now >= (creds.expiresAt - 60_000);
+}
+
+/**
+ * Starts the loopback listener and returns the chosen port immediately, since
+ * the port has to go into the authorize URL before any code can arrive.
+ */
+export function startCallbackServer({ expectedState, expectedIssuer, timeoutMs = 300_000 }) {
+  return new Promise((resolveStart, rejectStart) => {
+    let settle;
+    const waitForCode = new Promise((resolve, reject) => { settle = { resolve, reject }; });
+
+    const server = http.createServer((req, res) => {
+      const url = new URL(req.url, 'http://127.0.0.1');
+      if (url.pathname !== '/callback') { res.writeHead(404).end('Not found'); return; }
+      try {
+        const code = validateCallback({ params: url.searchParams, expectedState, expectedIssuer });
+        res.writeHead(200, { 'Content-Type': 'text/html' }).end(page(
+          'Motorical is connected',
+          'You can close this tab and return to your terminal.'
+        ));
+        finish(); settle.resolve(code);
+      } catch (err) {
+        res.writeHead(400, { 'Content-Type': 'text/html' }).end(page(
+          'Authorization failed', escapeHtml(err.message)
+        ));
+        finish(); settle.reject(err);
+      }
+    });
+
+    const timer = setTimeout(() => {
+      finish();
+      settle.reject(new Error('Timed out waiting for the browser callback'));
+    }, timeoutMs);
+
+    function finish() {
+      clearTimeout(timer);
+      setImmediate(() => server.close(() => {}));
+    }
+
+    server.on('error', (err) => { clearTimeout(timer); rejectStart(err); });
+    // Port 0 = whatever the OS gives us; the AS matches loopback ignoring port.
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address();
+      resolveStart({
+        port,
+        redirectUri: `http://127.0.0.1:${port}/callback`,
+        waitForCode,
+        close: finish,
+      });
+    });
+  });
+}
+
+function page(title, body) {
+  return `<html><body style="font-family:system-ui;padding:3rem;text-align:center"><h2>${title}</h2><p>${body}</p></body></html>`;
+}
+
+function escapeHtml(s) {
+  return String(s).replace(/[&<>"']/g, (c) => (
+    { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]
+  ));
+}