@ezmodo/mcp-server 0.13.5 → 0.14.1

package/README.md

@@ -2,73 +2,114 @@
 
 Model Context Protocol (MCP) server for ezmodo - AI-first project management.
 
-## Installation
+## Install
 
-### Global Installation (Recommended)
+Point any MCP client at the package. There is nothing to configure:
 
-```bash
-npm install -g @ezmodo/mcp-server
+```json
+{
+  "mcpServers": {
+    "ezmodo": {
+      "command": "npx",
+      "args": ["-y", "@ezmodo/mcp-server"]
+    }
+  }
+}
 ```
 
-### Local Installation
+The first tool call returns a sign-in URL. Open it, approve the access, and
+retry — the server holds the token from then on and refreshes it itself. No API
+key, no environment variable, no CLI.
 
-For local development, use the ezmodo CLI (recommended):
-
-```bash
-# Install CLI
-curl -fsSL https://ezmodo.com/cli/install/scripts/latest/install.sh | sh
+That block is the same for Claude Desktop, Cursor, Windsurf, Zed, Codex and
+anything else that speaks stdio MCP; only the file it goes in differs.
 
-# Authenticate
-ezmodo auth login
+**Claude Code users should install the plugin instead**, which bundles this
+server along with the work-tracking skills, slash commands and hooks:
 
-# Configure MCP
-ezmodo mcp install
 ```
+/plugin marketplace add EasyModeOnly/ezmodo-plugins
+/plugin install ezmodo@ezmodo
+```
+
+### Signing in
 
-## Prerequisites
+Sign-in happens through the `authenticate` tool rather than at startup, because
+a server launched by an editor has no terminal to prompt in:
 
-1. **ezmodo Account**: Sign up at [ezmodo.com](https://ezmodo.com)
-2. **API Key**: Generate an API key in your ezmodo account settings
+| Action | What it does |
+| --- | --- |
+| `authenticate` | Starts browser sign-in and returns the URL to open |
+| `authenticate action:"status"` | Reports which credential is in use |
+| `authenticate action:"sign_out"` | Forgets the stored tokens |
 
-### Generating an API Key
+It returns the URL immediately rather than blocking until you finish in the
+browser, so it cannot trip a client's tool-call timeout. Approve, then retry
+whatever you were doing.
 
-1. Log in to [ezmodo.com](https://ezmodo.com)
-2. Navigate to **Settings** → **API Keys**
-3. Click **Generate New API Key**
-4. Copy your API key
-5. Store it securely - you won't be able to see it again!
+Tokens are stored at `~/.config/ezmodo/mcp-oauth.json` (`%APPDATA%\ezmodo\` on
+Windows), mode `0600`.
 
-## Configuration
+The sign-in asks for `ezmodo:read` and `ezmodo:write`. It deliberately does not
+ask for `ezmodo:delete`: consent is accept-or-decline over the whole set, and
+"permanently delete your projects" should not be a condition of installing an
+MCP server. Set `EZMODO_OAUTH_SCOPES` if you want a different set.
 
-### For Claude Desktop
+## Using an API key instead
 
-Add to your `claude_desktop_config.json`:
+For CI, containers and anything headless where no browser exists, set
+`EZMODO_API_KEY` and skip sign-in entirely:
 
 ```json
 {
   "mcpServers": {
     "ezmodo": {
-      "command": "ezmodo-mcp-server",
+      "command": "npx",
+      "args": ["-y", "@ezmodo/mcp-server"],
       "env": {
-        "EZMODO_API_KEY": "your_api_key_here",
-        "EZMODO_API_URL": "https://ezmodo.com/api"
+        "EZMODO_API_KEY": "ezm_sk_your_key_here"
       }
     }
   }
 }
 ```
 
-**Configuration Options:**
+Generate one at **Settings → API Keys** on [ezmodo.com](https://ezmodo.com).
+Keys start with `ezm_sk_` and are shown once. Pre-rename `zeph_sk_` keys remain
+valid indefinitely.
+
+### Which credential wins
+
+Resolved per call, in this order:
+
+1. `EZMODO_API_KEY` (or legacy `ZEPHLY_API_KEY`) — an explicit credential beats
+   an implicit one, which is what keeps CI predictable.
+2. The OAuth token this server obtained for itself.
+3. The credential `ezmodo auth login` stored, if you happen to have the CLI.
+
+`authenticate action:"status"` reports which of these is actually in use.
+
+### Other environment variables
+
+- `EZMODO_API_URL` (optional): custom API URL. Defaults to production
+  (`https://ezmodo.com/api`).
+- `EZMODO_OAUTH_SCOPES` (optional): space-separated scopes to request at
+  sign-in.
+
+## What the server provides besides tools
 
-- `EZMODO_API_KEY` (required): Your ezmodo API key. Legacy `ZEPHLY_API_KEY` is still read as a fallback during the rebrand transition.
-- `EZMODO_API_URL` (optional): Custom API URL. Defaults to production (`https://ezmodo.com/api`).
+**Instructions.** The initialize result carries the work-tracking contract —
+create the task before you edit, tick steps off, capture knowledge, link the
+commit, finish at `in_review`. Most clients inject it into system context, so
+the discipline travels with the tools rather than needing a per-editor plugin.
 
-### For Local Development
+**Prompts.** `start`, `resume`, `submit` and `untracked`, which clients surface
+as slash commands. `submit` is local-only, since it reads git SHAs.
 
-If running from source:
+## Running from source
 
 ```bash
-export EZMODO_API_KEY="your_api_key_here"
+export EZMODO_API_KEY="ezm_sk_your_key_here"
 export EZMODO_API_URL="http://localhost:8787/api"  # Local Go API
 npm run dev
 ```
@@ -248,21 +289,50 @@ When working with the MCP tools:
 
 ## Troubleshooting
 
-### "Missing Authorization header"
-- Ensure `EZMODO_API_KEY` is set in your configuration
+### "Not authenticated with EzModo"
+Nobody has signed in and no `EZMODO_API_KEY` is set. Call `authenticate`, open
+the URL it returns, then retry. Tool calls return this as guidance rather than a
+bare error, so the agent can act on it.
+
+### A 403 after signing in successfully
+Signing in worked; the account just does not belong to any EzModo organization
+yet, so there is nothing for tools to return. Signing in again will not change
+it — no credential substitutes for belonging to a workspace.
+
+Tool calls answer this one themselves: the result carries an `onboardingUrl`,
+and opening it lets you create a personal workspace, create a team, or ask to
+join an organization your verified email already matches. If you expected to be
+a member of one already, you are probably signed in as a different identity than
+you think — check which email that page shows, and ask an administrator to
+invite that exact address.
+
+### "This email address already belongs to a different EzModo account"
+Sign-in worked, but no account could be created for the identity you signed in
+with, because that address is already registered under a different one — most
+often a password account and a Google/Microsoft/GitHub/Apple sign-in for the
+same person. Creating a workspace will not help; the same collision happens
+there. Sign in the way you originally did, or contact support to have the two
+linked.
+
+### Sign-in never completes
+The flow needs a browser — this client cannot take a username and password
+directly, because skipping the browser would skip the consent screen. If no
+browser can open (over SSH, or in a container), the URL is still in the tool
+result; open it anywhere and approve. Or set `EZMODO_API_KEY` instead, which is
+the right answer for a headless machine.
 
 ### "Invalid or revoked API key"
-- Regenerate your API key in ezmodo settings
-- Ensure the key hasn't expired or been revoked
+Regenerate the key in ezmodo settings. Check it has not been revoked, and that
+it has not passed an expiry date if you set one.
 
 ### "Failed to connect to API"
 - Check your `EZMODO_API_URL` configuration
 - Verify your internet connection
 
-### Claude Desktop doesn't see the server
-- Restart Claude Desktop after updating config
+### The client doesn't see the server
+- Restart it after updating config — MCP servers are read at startup
 - Check the config file path is correct
-- Verify JSON syntax in `claude_desktop_config.json`
+- Verify the JSON syntax
 
 ## Development
 

package/handlers/auth.js

@@ -0,0 +1,160 @@
+/**
+ * Sign-in handlers (#2632).
+ *
+ * THE SHAPE THAT MATTERS: `login` returns as soon as it has a URL, and does
+ * NOT wait for the user.
+ *
+ * Blocking until the browser round trip finished would read better in a
+ * transcript — one call, "signed in as you" — but it puts a human's attention
+ * span on the critical path of a tool call. Clients time tool calls out at
+ * wildly different limits, and a client that gives up at thirty seconds would
+ * report a failure for a sign-in that then succeeds in the background, leaving
+ * the agent with a wrong answer and the user with a working login. Returning
+ * immediately is correct under every timeout.
+ *
+ * The flow keeps running after the return: the loopback listener is alive in
+ * this process, and completion writes the tokens itself. So the recovery is
+ * simply for the agent to retry whatever it was doing.
+ */
+
+import { beginLogin, getSignedInIdentity, signOut } from '../lib/oauth.js';
+import { getApiKey } from '../lib/env.js';
+import { signInRequired } from '../lib/auth-guidance.js';
+import { resetCredentialCache } from '../lib/credentials.js';
+import { getLogger } from '../lib/logger.js';
+
+/**
+ * The sign-in currently waiting on a browser, if any.
+ *
+ * Held so a second `login` while one is already open returns the SAME URL
+ * rather than starting a rival flow. Two live flows would mean two loopback
+ * listeners and two states, and whichever URL the user did not click would sit
+ * there until it timed out.
+ */
+let pending = null;
+
+/**
+ * Abandon a sign-in that is still waiting on a browser.
+ *
+ * Real behaviour, not just a test seam: signing out while a browser tab is
+ * still open should not leave a loopback listener alive that would quietly
+ * complete the login the user just cancelled.
+ */
+export function cancelPendingLogin() {
+  if (!pending) return false;
+  pending.cancel();
+  pending = null;
+  return true;
+}
+
+/** Open a URL in the user's browser, best-effort. */
+async function openBrowser(url) {
+  const { execFile } = await import('child_process');
+  const commands =
+    process.platform === 'darwin'
+      ? [['open', [url]]]
+      : process.platform === 'win32'
+        ? [['cmd', ['/c', 'start', '', url]]]
+        : [
+          ['xdg-open', [url]],
+          ['sensible-browser', [url]],
+          ['x-www-browser', [url]],
+        ];
+
+  for (const [command, args] of commands) {
+    const opened = await new Promise((resolve) => {
+      // execFile, not exec: no shell, so a URL cannot be read as shell syntax.
+      execFile(command, args, (error) => resolve(!error));
+    });
+    if (opened) return true;
+  }
+  // Not a failure. The URL in the result is the contract; the browser launch
+  // is a convenience, and it is expected to fail over SSH or in a container.
+  return false;
+}
+
+async function login() {
+  const log = getLogger();
+
+  if (pending) {
+    return {
+      ...signInRequired({ authUrl: pending.authUrl, reason: 'A sign-in is already waiting.' }),
+      browserOpened: pending.browserOpened,
+    };
+  }
+
+  const flow = await beginLogin();
+  const browserOpened = await openBrowser(flow.authUrl);
+
+  pending = { authUrl: flow.authUrl, browserOpened, cancel: flow.cancel };
+  flow
+    .complete()
+    .then((tokens) => {
+      // The credential chain memoizes the CLI lookup; drop it so the fresh
+      // OAuth token is what the next call sees.
+      resetCredentialCache();
+      log.info('Browser sign-in completed', { email: tokens.email });
+    })
+    .catch((error) => log.warn('Browser sign-in did not complete', { error: error.message }))
+    .finally(() => {
+      pending = null;
+    });
+
+
+  return {
+    ...signInRequired({
+      authUrl: flow.authUrl,
+      reason: 'Sign-in started. Waiting for you to approve it in a browser.',
+    }),
+    browserOpened,
+    next_step: browserOpened
+      ? 'A browser should have opened. Once approved, retry the call you were making.'
+      : 'No browser could be opened here — show the URL to the user, then retry the call.',
+  };
+}
+
+function status() {
+  const envKey = getApiKey();
+  if (envKey) {
+    return {
+      authenticated: true,
+      source: 'EZMODO_API_KEY',
+      note: 'An explicit key is set, so it takes precedence over any browser sign-in.',
+    };
+  }
+
+  const identity = getSignedInIdentity();
+  if (identity) {
+    return { authenticated: true, source: 'OAuth', ...identity };
+  }
+
+  return signInRequired({ reason: 'This server is not signed in.' });
+}
+
+/**
+ * @param {{ action?: 'login'|'status'|'sign_out' }} args
+ */
+export async function authenticate(args = {}) {
+  switch (args.action || 'login') {
+  case 'status':
+    return status();
+  case 'sign_out': {
+    // Cancel first: a listener left alive would complete the very sign-in
+    // being abandoned.
+    const cancelled = cancelPendingLogin();
+    signOut();
+    resetCredentialCache();
+    return {
+      signedOut: true,
+      cancelledPendingSignIn: cancelled,
+      note:
+          'Stored OAuth tokens removed. EZMODO_API_KEY and the ezmodo CLI login ' +
+          'are untouched — this server does not own either.',
+    };
+  }
+  case 'login':
+    return login();
+  default:
+    throw new Error(`Unknown action: ${args.action}. Use login, status or sign_out.`);
+  }
+}

package/handlers/index.js

@@ -38,12 +38,14 @@ import * as agentHandlers from './agents.js';
 import * as recurringTaskHandlers from './recurring-tasks.js';
 import * as workTemplateHandlers from './work-templates.js';
 import { manageWorktree, listProjectWorktrees } from '../lib/worktree-tools.js';
+import { authenticate } from './auth.js';
 
 /**
  * Map of tool names to handler functions
  * Used by the MCP server to route tool calls
  */
 export const HANDLERS = {
+  authenticate,
   // Organizations
   get_organization: organizationHandlers.getOrganization,
 

package/http.js

@@ -91,7 +91,12 @@ export function protectedResourceMetadata() {
     authorization_servers: AUTH_SERVER ? [AUTH_SERVER] : [],
     scopes_supported: CONSENT_SCOPES,
     bearer_methods_supported: ['header'],
-    resource_documentation: 'https://ezmodo.com/help/connectors',
+    // The DB-backed help centre, verified to resolve. /help/connectors was
+    // invented for this field and never existed — a dead link shipped inside a
+    // public discovery document, where nobody would notice because nothing in
+    // the handshake reads it.
+    resource_documentation:
+      process.env.MCP_DOCS_URL || 'https://ezmodo.com/docs/emo/ezmodo/help/cli-mcp',
   };
 }
 

package/index.js

@@ -15,8 +15,7 @@ import { CONFIG } from './config/index.js';
 // The tool surface, shared with the HTTP entry point (http.js).
 import { createServer } from './lib/create-server.js';
 import { initLogger, getLogger } from './lib/logger.js';
-import { getApiKey } from './lib/env.js';
-import { readCliCredential } from './lib/cli-credential.js';
+import { describeCredentialSync } from './lib/credentials.js';
 
 // ============================================================
 // Configuration Validation
@@ -26,66 +25,36 @@ import { readCliCredential } from './lib/cli-credential.js';
 initLogger();
 const log = getLogger();
 
-let apiKey = getApiKey();
-let apiKeySource = 'EZMODO_API_KEY';
-
-// Fall back to the credential `ezmodo auth login` already stored (#2611).
+// The credential is REPORTED here, not required here.
 //
-// The environment always wins: an explicit key must beat an implicit one, or
-// overriding it for a single project becomes impossible to reason about. This
-// only runs when there is nothing to override.
+// This used to exit(1) when it found no API key, which was right when a key
+// was the only way in: a server that cannot authenticate can do nothing, so
+// failing loudly beat failing on every tool call. OAuth changes that (#2631) —
+// signing in happens through the browser AFTER startup, so a server with no
+// credential yet is not broken, it is waiting. Exiting would make the one case
+// we now want to support impossible.
 //
-// Assigning to process.env rather than threading the value through is
-// deliberate — lib/http-client.js re-reads getApiKey() on every request, so
-// this is the one place that has to know. It is the same thing the CLI's own
-// startMcpServer does before importing a handler.
-if (!apiKey) {
-  const stored = readCliCredential();
-  if (stored) {
-    process.env.EZMODO_API_KEY = stored.key;
-    apiKey = stored.key;
-    apiKeySource = stored.source;
-  }
-}
-
-if (!apiKey) {
-  log.error('No API key: EZMODO_API_KEY is unset and no ezmodo CLI credential was found', {
-    settingsUrl: CONFIG.settingsUrl,
-  });
-  console.error('ERROR: No ezmodo API key found.');
-  console.error('');
-  console.error('Checked, in order:');
-  console.error('  1. EZMODO_API_KEY (or legacy ZEPHLY_API_KEY) — not set');
-  console.error('  2. the credential stored by `ezmodo auth login` — not found');
-  console.error('');
-  console.error('Fix it either way:');
-  console.error('  • run `ezmodo auth login`, or');
-  console.error('  • set EZMODO_API_KEY in the environment');
-  console.error('');
-  console.error(`Generate a key at: ${CONFIG.settingsUrl}`);
-  console.error('\nOptional environment variables:');
-  console.error('- EZMODO_API_URL (default: production Go API URL)');
-  console.error('- EZMODO_ENVIRONMENT (dev/staging/production)');
-  console.error('\nEnvironment-specific URLs:');
-  console.error('  - dev: https://dev.ezmodo.com/api');
-  console.error('  - staging: https://staging.ezmodo.com/api');
-  console.error('  - production: https://ezmodo.com/api');
-  console.error('  - local: http://localhost:8787/api');
-  process.exit(1);
-}
+// Nothing is resolved asynchronously here either: a stale token would make the
+// server block on Keycloak before it ever spoke MCP. The refresh happens on
+// the first call that needs one.
+const credential = describeCredentialSync();
 
 log.info('MCP server starting', {
   environment: CONFIG.environment,
   apiUrl: CONFIG.apiUrl,
-  apiKeyPrefix: apiKey.substring(0, 12),
-  apiKeySource,
+  credentialSource: credential?.source ?? 'none',
 });
 console.error('🔧 ezmodo MCP Server Configuration:');
 console.error(`   Environment: ${CONFIG.environment} (build-time)`);
 console.error(`   API URL: ${CONFIG.apiUrl}`);
-// Name the source. A server that silently authenticates as whoever the CLI
-// happens to be logged in as, with no way to tell, is worse than one that fails.
-console.error(`   API Key: ${apiKey.substring(0, 12)}... (from ${apiKeySource})`);
+if (credential) {
+  // Name the source. A server that silently authenticates as whoever the CLI
+  // happens to be logged in as, with no way to tell, is worse than one that fails.
+  console.error(`   Credential: ${credential.detail ?? ''} (from ${credential.source})`);
+} else {
+  console.error('   Credential: none yet — sign in with the `authenticate` tool');
+  console.error(`   Or set EZMODO_API_KEY. Generate a key at: ${CONFIG.settingsUrl}`);
+}
 console.error('');
 
 // ============================================================

package/lib/auth-guidance.js

@@ -0,0 +1,175 @@
+/**
+ * What an agent is told when a call cannot be authenticated (#2632).
+ *
+ * The hard problem this solves: a stdio MCP server is started headlessly by an
+ * editor, with no terminal a human is watching. It cannot say "go to this URL".
+ * The server's own clear startup message goes to a stderr log nobody opens —
+ * which is exactly how #2611 produced an opaque CONNECTION_CLOSED instead of
+ * the message that was right there.
+ *
+ * So don't fight it. Use the channel the agent is already reading: the tool
+ * result. The agent shows the URL in chat, the user clicks, the agent retries.
+ * This is the pattern the claude.ai connector already uses, and it is better UX
+ * than an environment variable rather than a workaround for one.
+ *
+ * Everything here is DATA in a tool result, never a thrown transport error: a
+ * result is something the model can read and act on, an exception is not.
+ */
+
+import { CONFIG } from '../config/index.js';
+
+/** Marks the "there is no credential at all" failure, so dispatch can spot it. */
+export const NOT_AUTHENTICATED = 'EZMODO_NOT_AUTHENTICATED';
+
+/**
+ * The API's code for "signed in, but in no organization" (#2639).
+ *
+ * Must match middleware.CodeNoOrganization in
+ * api/internal/api/middleware/oidc_mcp_auth.go. A code rather than a message
+ * match, because the message is prose someone will improve.
+ */
+export const NO_ORGANIZATION = 'NO_ORGANIZATION';
+
+/**
+ * The API's code for "this email already belongs to another identity" (#2652).
+ *
+ * Must match middleware.CodeEmailAlreadyRegistered. Kept separate from
+ * NO_ORGANIZATION because the answers point opposite ways: that one sends you
+ * to onboarding, and onboarding is exactly where this one fails again.
+ */
+export const EMAIL_ALREADY_REGISTERED = 'EMAIL_ALREADY_REGISTERED';
+
+/**
+ * The two things a user cannot guess, and will otherwise hit as bare failures.
+ *
+ * Stated on every sign-in prompt on purpose. Both are consequences of decisions
+ * made elsewhere, and neither is discoverable from the error the user would
+ * otherwise see.
+ */
+const CAVEATS = [
+  'A browser is required. This connector cannot take a username and password ' +
+    'directly — direct access grants are disabled on it deliberately, because ' +
+    'skipping the browser also skips the consent screen, which is the whole ' +
+    'reason for using OAuth here rather than a pasted key.',
+  'A brand-new EzModo account belongs to no organization yet, so tools will ' +
+    'return 403 until it does. That is an access problem, not a sign-in ' +
+    'problem — signing in again will not change it. The call that hits it ' +
+    'says how to fix it; see `organizationRequired` below.',
+];
+
+/**
+ * The payload returned when a sign-in is needed.
+ *
+ * @param {object} options
+ * @param {string} [options.authUrl] The URL to open, when a flow has started.
+ * @param {string} [options.reason]  What went wrong, in one line.
+ */
+export function signInRequired({ authUrl, reason } = {}) {
+  return {
+    authenticated: false,
+    reason: reason || 'No EzModo credential is available.',
+    ...(authUrl
+      ? {
+        action_required: 'Open this URL in a browser, approve the access, then retry the call.',
+        authUrl,
+      }
+      : {
+        action_required:
+            'Call the `authenticate` tool to start sign-in. It returns a URL to open.',
+      }),
+    alternatives: [
+      `Set EZMODO_API_KEY in the environment instead — generate a key at ${CONFIG.settingsUrl}. ` +
+        'This is the right path for CI and anything headless.',
+    ],
+    notes: CAVEATS,
+  };
+}
+
+/**
+ * The payload returned when the caller is signed in but belongs to no
+ * organization (#2639).
+ *
+ * Why this is a separate answer from `signInRequired`, and not a widening of
+ * it: sign-in already worked. Sending this person back through a browser flow
+ * produces the identical token and the identical failure, which is precisely
+ * why #2632 kept 403 out of that funnel. What they need is the OTHER half of
+ * onboarding — a workspace — and EzModo already has a surface for it.
+ *
+ * SO THIS DOES NOT INVENT A MECHANISM. The web app routes a signed-in user
+ * with no organizations to /onboarding, which offers a personal workspace, a
+ * new team, or /join — workspace discovery, which lists organizations matching
+ * a verified email domain and joins none of them without a click. Matching an
+ * organization here instead would be a second, quieter copy of that consent
+ * decision, and the quiet copy is the one that gets it wrong.
+ *
+ * Returned on BOTH surfaces, unlike the sign-in prompt. Over the connector
+ * Claude owns the OAuth, so sign-in advice from here would be wrong — but the
+ * missing workspace is ours either way, and a claude.ai user hits it exactly
+ * as a local one does.
+ *
+ * @param {object} options
+ * @param {string} [options.reason] What the API said, in one line.
+ */
+export function organizationRequired({ reason } = {}) {
+  return {
+    authenticated: true,
+    organization: null,
+    reason:
+      reason ||
+      'This account is signed in but does not belong to any EzModo organization.',
+    action_required:
+      'Open the URL below and finish setting up a workspace, then retry the call. ' +
+      'You can create a personal workspace, create a team, or ask to join an ' +
+      'organization your verified email already matches.',
+    onboardingUrl: `${CONFIG.webUrl}/onboarding`,
+    notes: [
+      'Sign-in itself succeeded. Signing in again will not change this, and ' +
+        'no credential — OAuth token or API key — can substitute for belonging ' +
+        'to an organization.',
+      'If you expected to already be a member of one, you are probably signed ' +
+        `in as a different identity than you think. Check which email ${CONFIG.webUrl}/onboarding ` +
+        'shows, and ask an administrator to invite that exact address.',
+    ],
+  };
+}
+
+/**
+ * The payload returned when sign-in succeeded but no account could be created
+ * for it, because the email already belongs to a different EzModo identity
+ * (#2652).
+ *
+ * The reason this is not folded into `organizationRequired`: both used to look
+ * identical from outside — a signed-in caller getting nothing back — and the
+ * fix for one is a dead end for the other. Creating a workspace runs the same
+ * insert against the same unique index and fails the same way. Telling someone
+ * to go do that is worse than telling them nothing, because they will believe
+ * it and try.
+ *
+ * There is deliberately no self-service action here. Merging two identities
+ * onto one account is exactly the operation that must not be automated from an
+ * unauthenticated-by-the-other-party direction, so the honest answer is the
+ * original sign-in method, or a human.
+ *
+ * @param {object} options
+ * @param {string} [options.reason] What the API said, in one line.
+ */
+export function emailAlreadyRegistered({ reason } = {}) {
+  return {
+    authenticated: true,
+    accountProvisioned: false,
+    reason:
+      reason ||
+      'This email address already belongs to a different EzModo account, so no ' +
+        'account could be created for the identity you signed in with.',
+    action_required:
+      'Sign in the way you originally did — a password, or whichever of Google, ' +
+        'Microsoft, GitHub or Apple you used first. If you need the two linked, ' +
+        'contact support.',
+    notes: [
+      'Creating a workspace will NOT fix this, and neither will signing in ' +
+        'again through the same provider. Nothing is wrong with the sign-in; ' +
+        'the account simply could not be created.',
+      `You can check which address is in use at ${CONFIG.webUrl}/settings.`,
+    ],
+  };
+}