@rndmjoker/proton-mcp 0.4.4

package/dist/server.js

@@ -0,0 +1,387 @@
+#!/usr/bin/env node
+/**
+ * Entry point of the MCP server.
+ *
+ * The server speaks over stdio, so the client starts it as a child process.
+ * That is not a workaround: the Bridge only listens on 127.0.0.1, so a server
+ * running in the cloud could not reach it at all.
+ *
+ * The local web interface runs for as long as this process does. It is not
+ * started on demand: it is where configuration and state live, and it is meant
+ * to be opened again and again rather than summoned for one sign-in.
+ */
+import { createRequire } from 'node:module';
+import { randomBytes } from 'node:crypto';
+import { McpServer, createRequestStateCodec } from '@modelcontextprotocol/server';
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
+import { loadConfig, credentialsFromEnvironment, portsSetExplicitly, ConfigError, } from './config.js';
+import { Connection } from './bridge/connection.js';
+import { loadPinned, pinPath } from './bridge/certificate.js';
+import { Session } from './session.js';
+import { encryptedFilePath } from './credentials/encrypted-file.js';
+import { loadSettings, saveSettings } from './settings.js';
+import * as activity from './activity.js';
+import { WebInterface } from './web/server.js';
+import { registerListFolders } from './tools/list-folders.js';
+import { registerMessageTools } from './tools/messages.js';
+import { registerInterfaceTool } from './tools/interface.js';
+import { registerLabelTools } from './tools/labels.js';
+import { registerActionTools } from './tools/actions.js';
+import { registerDraftTools } from './tools/drafts.js';
+import { registerSendTools } from './tools/send.js';
+import { setSignInHint, setLockedCheck } from './tools/failures.js';
+import { setHandshakeCapabilities } from './tools/capabilities.js';
+import { registerGuidance, INSTRUCTIONS } from './tools/guidance.js';
+import { waitForIdle } from './in-flight.js';
+// The version number lives in package.json only.
+// Writing it here a second time would mean forgetting it here. From
+// dist/server.js the path points at the package.json of the project root, and
+// in the published package at its own.
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+/**
+ * What this server calls itself, which is deliberately not the package name.
+ *
+ * The package is scoped so that other servers can sit beside it under the same
+ * namespace. That scope is an ownership statement for a registry and has no
+ * business in a protocol handshake or at the front of every line on stderr,
+ * where it would only make both harder to read.
+ *
+ * Fixed here rather than derived, because deriving it would tie the name a
+ * client displays to a decision about where the package is published.
+ */
+const NAME = 'proton-mcp';
+const VERSION = pkg.version;
+const notify = (message) => {
+    // stderr, never stdout: the protocol runs over stdout.
+    process.stderr.write(`${NAME}: ${message}\n`);
+};
+async function main() {
+    const startedAt = Date.now();
+    let config;
+    try {
+        config = loadConfig();
+    }
+    catch (error) {
+        if (error instanceof ConfigError) {
+            process.stderr.write(`${NAME}: ${error.message}\n`);
+            process.exit(1);
+        }
+        throw error;
+    }
+    // Stored ports fill in only where the environment said nothing. An explicit
+    // BRIDGE_IMAP_PORT has to keep meaning what it says.
+    const explicitPorts = portsSetExplicitly();
+    // Held rather than read once: every write goes through the whole object, so
+    // that saving one setting cannot drop another. saveSettings replaces the file.
+    const settings = await loadSettings();
+    if (!explicitPorts.imapPort && settings.imapPort !== undefined)
+        config.imapPort = settings.imapPort;
+    if (!explicitPorts.smtpPort && settings.smtpPort !== undefined)
+        config.smtpPort = settings.smtpPort;
+    const environmentCredentials = credentialsFromEnvironment();
+    const session = new Session({
+        ...(environmentCredentials ? { fromEnvironment: environmentCredentials } : {}),
+        notify,
+    });
+    // One connection for the whole process, opened on the first tool call rather
+    // than at startup: a client often spawns the server long before the user wants
+    // anything, and a locked Bridge should not prevent it from starting.
+    const connection = new Connection(config, () => session.credentials(), notify);
+    /**
+     * Tries credentials against the Bridge before they are trusted.
+     *
+     * Storing something that does not work would send the user looking in the
+     * wrong place, and on the unlock path it is the only way to tell a wrong
+     * master password from a Bridge that is simply locked.
+     */
+    const verify = async (credentials) => {
+        const probe = new Connection(config, async () => credentials, notify);
+        try {
+            await probe.listMailboxes();
+            return undefined;
+        }
+        catch (error) {
+            return error.message;
+        }
+        finally {
+            await probe.close();
+        }
+    };
+    const web = new WebInterface({
+        port: config.webPort,
+        onSignIn: async (credentials, storeKind, masterPassword) => {
+            const failure = await verify(credentials);
+            if (failure)
+                return failure;
+            try {
+                await session.signIn(credentials, storeKind, masterPassword);
+            }
+            catch (error) {
+                return error.message;
+            }
+            // Drop the old connection so the next call uses the new credentials.
+            await connection.close();
+            return undefined;
+        },
+        onSignOut: async () => {
+            await session.signOut();
+            await connection.close();
+        },
+        onUnlock: async (masterPassword) => {
+            let credentials;
+            try {
+                credentials = await session.unlock(masterPassword);
+            }
+            catch (error) {
+                return error.message;
+            }
+            // The file opened, which only says the master password was right. Whether
+            // the Bridge still accepts what was in it is a separate question, and one
+            // the user would rather have answered here than at the next tool call.
+            const failure = await verify(credentials);
+            if (failure) {
+                await session.signOut();
+                return (`${failure}\n\nThe file was decrypted, so the master password was correct, but the ` +
+                    'Bridge password inside it no longer works. Sign in again with a fresh one.');
+            }
+            await connection.close();
+            return undefined;
+        },
+        onDiscardEncrypted: async () => {
+            await session.discardEncrypted();
+            notify('the encrypted credentials file was deleted on request');
+        },
+        getStatus: async () => {
+            const pinned = loadPinned(pinPath());
+            const base = {
+                connected: session.signedIn,
+                locked: await session.locked(),
+                encryptedPath: encryptedFilePath(),
+                bridgeHost: config.host,
+                bridgeImapPort: config.imapPort,
+                bridgeSmtpPort: config.smtpPort,
+                readOnly: config.readOnly,
+                uptimeMs: Date.now() - startedAt,
+                ...(session.address ? { address: session.address } : {}),
+                ...(session.storeKind ? { storeKind: session.storeKind } : {}),
+                ...(pinned
+                    ? {
+                        certificate: {
+                            fingerprint: pinned.fingerprint256,
+                            subject: pinned.subject,
+                            firstSeen: pinned.firstSeen,
+                        },
+                    }
+                    : {}),
+            };
+            if (!session.signedIn)
+                return base;
+            try {
+                const mailboxes = await connection.listMailboxes();
+                const inbox = await connection.status('INBOX');
+                return {
+                    ...base,
+                    mailboxCount: mailboxes.filter((box) => box.selectable).length,
+                    messageCount: inbox.messages,
+                    unseenCount: inbox.unseen,
+                };
+            }
+            catch {
+                // The status page should still render when the Bridge is unreachable.
+                return base;
+            }
+        },
+        // Absent when the user set the ports themselves: the form then disappears
+        // rather than quietly overriding what they configured.
+        ...(explicitPorts.imapPort || explicitPorts.smtpPort
+            ? {}
+            : {
+                onPorts: async (ports) => {
+                    try {
+                        await saveSettings({ ...settings, ...ports });
+                    }
+                    catch (error) {
+                        return `The ports could not be saved: ${error.message}`;
+                    }
+                    settings.imapPort = ports.imapPort;
+                    settings.smtpPort = ports.smtpPort;
+                    // The Connection reads this object on every reconnect, so closing
+                    // the current one is all that is needed for the change to take.
+                    config.imapPort = ports.imapPort;
+                    config.smtpPort = ports.smtpPort;
+                    await connection.close();
+                    notify(`ports changed to IMAP ${ports.imapPort}, SMTP ${ports.smtpPort}`);
+                    return undefined;
+                },
+            }),
+        noticeDismissed: () => settings.noticeDismissed === true,
+        onDismissNotice: async () => {
+            settings.noticeDismissed = true;
+            try {
+                await saveSettings(settings);
+            }
+            catch (error) {
+                // Worth a line, not worth failing over: the notice is hidden for this
+                // run either way, and the next start simply shows it again.
+                notify(`the dismissed notice could not be remembered: ${error.message}`);
+            }
+        },
+        onTest: async () => {
+            try {
+                const mailboxes = await connection.listMailboxes();
+                return {
+                    ok: true,
+                    message: `The Bridge answered on ${config.host}:${config.imapPort} and accepted the ` +
+                        `credentials. ${mailboxes.filter((box) => box.selectable).length} mailboxes are visible.`,
+                };
+            }
+            catch (error) {
+                return { ok: false, message: error.message };
+            }
+        },
+        getMailboxes: () => connection.listMailboxes(),
+        getActivity: () => {
+            const now = Date.now();
+            return {
+                running: activity.inProgress().map((call) => ({
+                    tool: call.tool,
+                    forMs: now - call.startedAt,
+                })),
+                recent: activity.recent().map((call) => ({
+                    tool: call.tool,
+                    at: call.startedAt,
+                    durationMs: call.durationMs,
+                    outcome: call.outcome,
+                })),
+            };
+        },
+        notify,
+    });
+    // Every tool answer about a missing sign-in names this address, so the model
+    // sends the user there instead of asking for the password in the chat.
+    setSignInHint(() => (web.running ? web.url : undefined));
+    // So that a tool called while an encrypted file is still closed says what is
+    // actually missing: the master password, not the Bridge password.
+    setLockedCheck(() => session.locked());
+    let webUrl;
+    try {
+        webUrl = await web.start();
+        notify(`web interface at ${webUrl}`);
+        if (!session.signedIn && !environmentCredentials) {
+            // Asking the session restores from a store, which is what makes this
+            // message true. Without it the answer is always "nothing stored": the
+            // restore is lazy and has not happened yet at startup, so a perfectly
+            // good credentials file was reported as absent every single start.
+            const restored = await session.credentials();
+            if (restored) {
+                notify(`credentials restored from the ${session.storeKind ?? 'store'}, signed in as ${session.address}`);
+            }
+            else {
+                notify((await session.locked())
+                    ? 'credentials are stored in an encrypted file, open the address above to unlock them'
+                    : 'no credentials stored yet, open the address above to sign in');
+            }
+        }
+    }
+    catch (error) {
+        // A web interface that cannot start must not stop the server: with
+        // credentials in the environment everything else still works.
+        notify(`${error.message} Continuing without it.`);
+    }
+    /**
+     * Seals the confirmation that has to survive a round trip through the client.
+     *
+     * The key is random and lives only in this process, which is exactly right
+     * here: the server speaks over stdio, so the same process serves every round
+     * of a flow, and a key that never reaches disk cannot be stolen from it. A
+     * restart invalidates any confirmation in flight, which is the safe direction
+     * to fail in.
+     *
+     * Bound to the request method as well, so a sealed state cannot be lifted out
+     * of one kind of request and presented in another. Which tool it belongs to is
+     * checked separately, in the handler.
+     */
+    const sendCodec = createRequestStateCodec({
+        key: randomBytes(32),
+        // Long enough to read a confirmation and think about it, short enough that
+        // a yes does not stay usable for the rest of the day.
+        ttlSeconds: 300,
+        bind: (requestCtx) => String(requestCtx.mcpReq?.method ?? ''),
+    });
+    const handle = serveStdio(() => {
+        const server = new McpServer({ name: NAME, version: VERSION }, {
+            // Verifies the seal before a handler ever runs, and hands the decoded
+            // payload to it. Without this the state would come back as a raw
+            // string the client could have written itself.
+            requestState: { verify: sendCodec.verify },
+            // Travels with every connection, so it costs context on every session.
+            // It names only what a model would otherwise get wrong before it had a
+            // reason to look anything up; the detail lives in the resources.
+            instructions: INSTRUCTIONS,
+        });
+        registerGuidance(server);
+        registerListFolders(server, connection);
+        registerMessageTools(server, connection);
+        // Read as a function rather than a value: whether the server may write is a
+        // property of the configuration, and the tools should ask at call time.
+        registerLabelTools(server, connection, () => config.readOnly);
+        registerActionTools(server, connection, () => config.readOnly);
+        registerDraftTools(server, connection, () => config.readOnly, () => session.address);
+        // What the client declared at handshake time. On this SDK's protocol
+        // revision it is the only place the declaration exists, and the confirmation
+        // before sending refuses when it cannot see one. Registered here because the
+        // instance is built here and does not exist earlier.
+        setHandshakeCapabilities(() => server.server?.getClientCapabilities?.());
+        registerSendTools(server, {
+            config,
+            connection,
+            getCredentials: () => session.credentials(),
+            readOnly: () => config.readOnly,
+            from: () => session.address,
+            codec: sendCodec,
+        });
+        registerInterfaceTool(server, {
+            url: () => web.url,
+            running: () => web.running,
+            signedIn: () => session.signedIn,
+            address: () => session.address,
+            storeKind: () => session.storeKind,
+            locked: () => session.locked(),
+        });
+        return server;
+    });
+    // Clean shutdown. stdin matters most: when the client dies the stream ends
+    // without any signal arriving. Without handling this, the server process
+    // would be left orphaned along with its open IMAP connection and its socket.
+    let shuttingDown = false;
+    const shutdown = async () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        // Give the event loop one turn first. When the input stream ends there may
+        // still be unread messages in the buffer that do not count as in-flight
+        // work yet. Without this pause the counter would be zero and the server
+        // would exit before the last request even starts.
+        await new Promise((next) => setTimeout(next, 50));
+        // Let running tool calls finish so their answer still goes out. Bounded,
+        // so that a stuck call cannot prevent shutdown.
+        const idle = await waitForIdle(5000);
+        if (!idle)
+            notify('shutdown forced, a call was still running.');
+        try {
+            await web.stop();
+            await connection.close();
+            await handle.close();
+        }
+        finally {
+            process.exit(idle ? 0 : 1);
+        }
+    };
+    process.stdin.on('end', () => void shutdown());
+    process.stdin.on('close', () => void shutdown());
+    process.on('SIGINT', () => void shutdown());
+    process.on('SIGTERM', () => void shutdown());
+}
+void main();
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":";AACA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,SAAS,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAA;AACjF,OAAO,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAA;AAC/D,OAAO,EACL,UAAU,EACV,0BAA0B,EAC1B,kBAAkB,EAClB,WAAW,GACZ,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAA;AAC7D,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAA;AACnE,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC1D,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AACzC,OAAO,EAAE,YAAY,EAAuB,MAAM,iBAAiB,CAAA;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AAC7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAEnD,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACnE,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAA;AAClE,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACpE,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAE5C,iDAAiD;AACjD,oEAAoE;AACpE,8EAA8E;AAC9E,uCAAuC;AACvC,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAA;AAC9C,MAAM,GAAG,GAAG,OAAO,CAAC,iBAAiB,CAAsC,CAAA;AAE3E;;;;;;;;;;GAUG;AACH,MAAM,IAAI,GAAG,YAAY,CAAA;AACzB,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAA;AAE3B,MAAM,MAAM,GAAG,CAAC,OAAe,EAAQ,EAAE;IACvC,uDAAuD;IACvD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,KAAK,OAAO,IAAI,CAAC,CAAA;AAC/C,CAAC,CAAA;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;IAE5B,IAAI,MAAM,CAAA;IACV,IAAI,CAAC;QACH,MAAM,GAAG,UAAU,EAAE,CAAA;IACvB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;YACjC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,KAAK,KAAK,CAAC,OAAO,IAAI,CAAC,CAAA;YACnD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QACjB,CAAC;QACD,MAAM,KAAK,CAAA;IACb,CAAC;IAED,4EAA4E;IAC5E,qDAAqD;IACrD,MAAM,aAAa,GAAG,kBAAkB,EAAE,CAAA;IAC1C,4EAA4E;IAC5E,+EAA+E;IAC/E,MAAM,QAAQ,GAAG,MAAM,YAAY,EAAE,CAAA;IACrC,IAAI,CAAC,aAAa,CAAC,QAAQ,IAAI,QAAQ,CAAC,QAAQ,KAAK,SAAS;QAAE,MAAM,CAAC,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAA;IACnG,IAAI,CAAC,aAAa,CAAC,QAAQ,IAAI,QAAQ,CAAC,QAAQ,KAAK,SAAS;QAAE,MAAM,CAAC,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAA;IAEnG,MAAM,sBAAsB,GAAG,0BAA0B,EAAE,CAAA;IAC3D,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC;QAC1B,GAAG,CAAC,sBAAsB,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,sBAAsB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9E,MAAM;KACP,CAAC,CAAA;IAEF,6EAA6E;IAC7E,+EAA+E;IAC/E,qEAAqE;IACrE,MAAM,UAAU,GAAG,IAAI,UAAU,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,MAAM,CAAC,CAAA;IAE9E;;;;;;OAMG;IACH,MAAM,MAAM,GAAG,KAAK,EAAE,WAA2C,EAA+B,EAAE;QAChG,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,EAAE,KAAK,IAAI,EAAE,CAAC,WAAW,EAAE,MAAM,CAAC,CAAA;QACrE,IAAI,CAAC;YACH,MAAM,KAAK,CAAC,aAAa,EAAE,CAAA;YAC3B,OAAO,SAAS,CAAA;QAClB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAQ,KAAe,CAAC,OAAO,CAAA;QACjC,CAAC;gBAAS,CAAC;YACT,MAAM,KAAK,CAAC,KAAK,EAAE,CAAA;QACrB,CAAC;IACH,CAAC,CAAA;IAED,MAAM,GAAG,GAAG,IAAI,YAAY,CAAC;QAC3B,IAAI,EAAE,MAAM,CAAC,OAAO;QACpB,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,cAAc,EAAE,EAAE;YACzD,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAA;YACzC,IAAI,OAAO;gBAAE,OAAO,OAAO,CAAA;YAC3B,IAAI,CAAC;gBACH,MAAM,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,SAAS,EAAE,cAAc,CAAC,CAAA;YAC9D,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAQ,KAAe,CAAC,OAAO,CAAA;YACjC,CAAC;YACD,qEAAqE;YACrE,MAAM,UAAU,CAAC,KAAK,EAAE,CAAA;YACxB,OAAO,SAAS,CAAA;QAClB,CAAC;QACD,SAAS,EAAE,KAAK,IAAI,EAAE;YACpB,MAAM,OAAO,CAAC,OAAO,EAAE,CAAA;YACvB,MAAM,UAAU,CAAC,KAAK,EAAE,CAAA;QAC1B,CAAC;QACD,QAAQ,EAAE,KAAK,EAAE,cAAc,EAAE,EAAE;YACjC,IAAI,WAAW,CAAA;YACf,IAAI,CAAC;gBACH,WAAW,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,CAAA;YACpD,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAQ,KAAe,CAAC,OAAO,CAAA;YACjC,CAAC;YACD,0EAA0E;YAC1E,0EAA0E;YAC1E,uEAAuE;YACvE,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAA;YACzC,IAAI,OAAO,EAAE,CAAC;gBACZ,MAAM,OAAO,CAAC,OAAO,EAAE,CAAA;gBACvB,OAAO,CACL,GAAG,OAAO,0EAA0E;oBACpF,4EAA4E,CAC7E,CAAA;YACH,CAAC;YACD,MAAM,UAAU,CAAC,KAAK,EAAE,CAAA;YACxB,OAAO,SAAS,CAAA;QAClB,CAAC;QACD,kBAAkB,EAAE,KAAK,IAAI,EAAE;YAC7B,MAAM,OAAO,CAAC,gBAAgB,EAAE,CAAA;YAChC,MAAM,CAAC,uDAAuD,CAAC,CAAA;QACjE,CAAC;QACD,SAAS,EAAE,KAAK,IAAI,EAAE;YACpB,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,EAAE,CAAC,CAAA;YACpC,MAAM,IAAI,GAAmB;gBAC3B,SAAS,EAAE,OAAO,CAAC,QAAQ;gBAC3B,MAAM,EAAE,MAAM,OAAO,CAAC,MAAM,EAAE;gBAC9B,aAAa,EAAE,iBAAiB,EAAE;gBAClC,UAAU,EAAE,MAAM,CAAC,IAAI;gBACvB,cAAc,EAAE,MAAM,CAAC,QAAQ;gBAC/B,cAAc,EAAE,MAAM,CAAC,QAAQ;gBAC/B,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;gBAChC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACxD,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC9D,GAAG,CAAC,MAAM;oBACR,CAAC,CAAC;wBACE,WAAW,EAAE;4BACX,WAAW,EAAE,MAAM,CAAC,cAAc;4BAClC,OAAO,EAAE,MAAM,CAAC,OAAO;4BACvB,SAAS,EAAE,MAAM,CAAC,SAAS;yBAC5B;qBACF;oBACH,CAAC,CAAC,EAAE,CAAC;aACR,CAAA;YACD,IAAI,CAAC,OAAO,CAAC,QAAQ;gBAAE,OAAO,IAAI,CAAA;YAClC,IAAI,CAAC;gBACH,MAAM,SAAS,GAAG,MAAM,UAAU,CAAC,aAAa,EAAE,CAAA;gBAClD,MAAM,KAAK,GAAG,MAAM,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;gBAC9C,OAAO;oBACL,GAAG,IAAI;oBACP,YAAY,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,MAAM;oBAC9D,YAAY,EAAE,KAAK,CAAC,QAAQ;oBAC5B,WAAW,EAAE,KAAK,CAAC,MAAM;iBAC1B,CAAA;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,sEAAsE;gBACtE,OAAO,IAAI,CAAA;YACb,CAAC;QACH,CAAC;QACD,0EAA0E;QAC1E,uDAAuD;QACvD,GAAG,CAAC,aAAa,CAAC,QAAQ,IAAI,aAAa,CAAC,QAAQ;YAClD,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC;gBACE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;oBACvB,IAAI,CAAC;wBACH,MAAM,YAAY,CAAC,EAAE,GAAG,QAAQ,EAAE,GAAG,KAAK,EAAE,CAAC,CAAA;oBAC/C,CAAC;oBAAC,OAAO,KAAK,EAAE,CAAC;wBACf,OAAO,iCAAkC,KAAe,CAAC,OAAO,EAAE,CAAA;oBACpE,CAAC;oBACD,QAAQ,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAA;oBAClC,QAAQ,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAA;oBAClC,kEAAkE;oBAClE,gEAAgE;oBAChE,MAAM,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAA;oBAChC,MAAM,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAA;oBAChC,MAAM,UAAU,CAAC,KAAK,EAAE,CAAA;oBACxB,MAAM,CAAC,yBAAyB,KAAK,CAAC,QAAQ,UAAU,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAA;oBACzE,OAAO,SAAS,CAAA;gBAClB,CAAC;aACF,CAAC;QACN,eAAe,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,eAAe,KAAK,IAAI;QACxD,eAAe,EAAE,KAAK,IAAI,EAAE;YAC1B,QAAQ,CAAC,eAAe,GAAG,IAAI,CAAA;YAC/B,IAAI,CAAC;gBACH,MAAM,YAAY,CAAC,QAAQ,CAAC,CAAA;YAC9B,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,sEAAsE;gBACtE,4DAA4D;gBAC5D,MAAM,CAAC,iDAAkD,KAAe,CAAC,OAAO,EAAE,CAAC,CAAA;YACrF,CAAC;QACH,CAAC;QACD,MAAM,EAAE,KAAK,IAAI,EAAE;YACjB,IAAI,CAAC;gBACH,MAAM,SAAS,GAAG,MAAM,UAAU,CAAC,aAAa,EAAE,CAAA;gBAClD,OAAO;oBACL,EAAE,EAAE,IAAI;oBACR,OAAO,EACL,0BAA0B,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,QAAQ,oBAAoB;wBAC5E,gBAAgB,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,MAAM,yBAAyB;iBAC5F,CAAA;YACH,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAG,KAAe,CAAC,OAAO,EAAE,CAAA;YACzD,CAAC;QACH,CAAC;QACD,YAAY,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,aAAa,EAAE;QAC9C,WAAW,EAAE,GAAG,EAAE;YAChB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;YACtB,OAAO;gBACL,OAAO,EAAE,QAAQ,CAAC,UAAU,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;oBAC5C,IAAI,EAAE,IAAI,CAAC,IAAI;oBACf,KAAK,EAAE,GAAG,GAAG,IAAI,CAAC,SAAS;iBAC5B,CAAC,CAAC;gBACH,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;oBACvC,IAAI,EAAE,IAAI,CAAC,IAAI;oBACf,EAAE,EAAE,IAAI,CAAC,SAAS;oBAClB,UAAU,EAAE,IAAI,CAAC,UAAU;oBAC3B,OAAO,EAAE,IAAI,CAAC,OAAO;iBACtB,CAAC,CAAC;aACJ,CAAA;QACH,CAAC;QACD,MAAM;KACP,CAAC,CAAA;IAEF,6EAA6E;IAC7E,uEAAuE;IACvE,aAAa,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAA;IACxD,6EAA6E;IAC7E,kEAAkE;IAClE,cAAc,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;IAEtC,IAAI,MAA0B,CAAA;IAC9B,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,GAAG,CAAC,KAAK,EAAE,CAAA;QAC1B,MAAM,CAAC,oBAAoB,MAAM,EAAE,CAAC,CAAA;QACpC,IAAI,CAAC,OAAO,CAAC,QAAQ,IAAI,CAAC,sBAAsB,EAAE,CAAC;YACjD,qEAAqE;YACrE,sEAAsE;YACtE,sEAAsE;YACtE,mEAAmE;YACnE,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,WAAW,EAAE,CAAA;YAC5C,IAAI,QAAQ,EAAE,CAAC;gBACb,MAAM,CAAC,iCAAiC,OAAO,CAAC,SAAS,IAAI,OAAO,kBAAkB,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;YAC1G,CAAC;iBAAM,CAAC;gBACN,MAAM,CACJ,CAAC,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC;oBACtB,CAAC,CAAC,oFAAoF;oBACtF,CAAC,CAAC,8DAA8D,CACnE,CAAA;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,mEAAmE;QACnE,8DAA8D;QAC9D,MAAM,CAAC,GAAI,KAAe,CAAC,OAAO,yBAAyB,CAAC,CAAA;IAC9D,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,MAAM,SAAS,GAAG,uBAAuB,CAAc;QACrD,GAAG,EAAE,WAAW,CAAC,EAAE,CAAC;QACpB,2EAA2E;QAC3E,sDAAsD;QACtD,UAAU,EAAE,GAAG;QACf,IAAI,EAAE,CAAC,UAAU,EAAE,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,IAAI,EAAE,CAAC;KAC9D,CAAC,CAAA;IAEF,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,EAAE;QAC7B,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,EAChC;YACE,sEAAsE;YACtE,iEAAiE;YACjE,+CAA+C;YAC/C,YAAY,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE;YAC1C,uEAAuE;YACvE,uEAAuE;YACvE,iEAAiE;YACjE,YAAY,EAAE,YAAY;SAC3B,CACF,CAAA;QACD,gBAAgB,CAAC,MAAM,CAAC,CAAA;QACxB,mBAAmB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;QACvC,oBAAoB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;QACxC,4EAA4E;QAC5E,wEAAwE;QACxE,kBAAkB,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;QAC7D,mBAAmB,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;QAC9D,kBAAkB,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;QACpF,qEAAqE;QACrE,6EAA6E;QAC7E,6EAA6E;QAC7E,qDAAqD;QACrD,wBAAwB,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,qBAAqB,EAAE,EAAE,CAAC,CAAA;QAExE,iBAAiB,CAAC,MAAM,EAAE;YACxB,MAAM;YACN,UAAU;YACV,cAAc,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE;YAC3C,QAAQ,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,QAAQ;YAC/B,IAAI,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO;YAC3B,KAAK,EAAE,SAAS;SACjB,CAAC,CAAA;QACF,qBAAqB,CAAC,MAAM,EAAE;YAC5B,GAAG,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG;YAClB,OAAO,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,OAAO;YAC1B,QAAQ,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,QAAQ;YAChC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO;YAC9B,SAAS,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,SAAS;YAClC,MAAM,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE;SAC/B,CAAC,CAAA;QACF,OAAO,MAAM,CAAA;IACf,CAAC,CAAC,CAAA;IAEF,2EAA2E;IAC3E,yEAAyE;IACzE,6EAA6E;IAC7E,IAAI,YAAY,GAAG,KAAK,CAAA;IACxB,MAAM,QAAQ,GAAG,KAAK,IAAmB,EAAE;QACzC,IAAI,YAAY;YAAE,OAAM;QACxB,YAAY,GAAG,IAAI,CAAA;QAEnB,2EAA2E;QAC3E,wEAAwE;QACxE,wEAAwE;QACxE,kDAAkD;QAClD,MAAM,IAAI,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAA;QAEjD,yEAAyE;QACzE,gDAAgD;QAChD,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,CAAA;QACpC,IAAI,CAAC,IAAI;YAAE,MAAM,CAAC,4CAA4C,CAAC,CAAA;QAE/D,IAAI,CAAC;YACH,MAAM,GAAG,CAAC,IAAI,EAAE,CAAA;YAChB,MAAM,UAAU,CAAC,KAAK,EAAE,CAAA;YACxB,MAAM,MAAM,CAAC,KAAK,EAAE,CAAA;QACtB,CAAC;gBAAS,CAAC;YACT,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;QAC5B,CAAC;IACH,CAAC,CAAA;IAED,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,EAAE,CAAC,CAAA;IAC9C,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,EAAE,CAAC,CAAA;IAChD,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,EAAE,CAAC,CAAA;IAC3C,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,EAAE,CAAC,CAAA;AAC9C,CAAC;AAED,KAAK,IAAI,EAAE,CAAA"}

package/dist/session.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The signed-in state of the server.
+ *
+ * Credentials used to be part of the configuration, read once at startup. That
+ * no longer works: with the web interface they can arrive at any time, and they
+ * can be revoked while the server keeps running. This is the one place that
+ * knows whether we are signed in.
+ *
+ * It also decides where credentials come from on startup, in this order:
+ *
+ * 1. Environment variables, when set. An explicit setting is never overruled.
+ * 2. The plain file, which is the interim path and the one existing setups use.
+ * 3. The system keyring, if something was stored there.
+ *
+ * The encrypted file is deliberately not in that list, because it cannot be:
+ * decrypting it needs a master password, and there is nowhere to ask for one
+ * while a stdio server starts up. It is instead reported as **locked**, which
+ * the web interface turns into a page asking for that one password. This is
+ * the whole reason `locked()` and `unlock()` exist rather than a fourth entry
+ * in the loop above.
+ */
+import type { Credentials, CredentialStore, StoreKind } from './credentials/store.js';
+export interface SessionOptions {
+    /** Credentials from the environment, when they were set. */
+    fromEnvironment?: Credentials;
+    /** Where notices go. stderr, never stdout, which carries the protocol. */
+    notify?: (message: string) => void;
+    /** Replaces the stores. Used by tests. */
+    stores?: Partial<Record<StoreKind, CredentialStore>>;
+}
+export declare class Session {
+    #private;
+    constructor(options?: SessionOptions);
+    get storeKind(): StoreKind | undefined;
+    get signedIn(): boolean;
+    /** The address we are signed in as, for display. Never the password. */
+    get address(): string | undefined;
+    /**
+     * Returns the credentials, restoring them from a store on first use.
+     *
+     * Restoring happens here rather than at startup so that a locked keyring
+     * cannot block the server from starting. It costs one attempt on the first
+     * tool call instead.
+     */
+    credentials(): Promise<Credentials | undefined>;
+    /**
+     * Whether credentials are stored that only a master password can open.
+     *
+     * Distinct from "not signed in": the user does not need to fetch their Bridge
+     * password from the Bridge again, they need to type one thing. A page that
+     * asked for everything would make the encrypted option feel broken.
+     */
+    locked(): Promise<boolean>;
+    /**
+     * Opens the encrypted file with the given master password.
+     *
+     * Returns the credentials so the caller can verify them against the Bridge.
+     * On failure the password is dropped again: keeping a wrong one would make
+     * every later attempt fail with a message about the file instead of about
+     * the password.
+     */
+    unlock(masterPassword: string): Promise<Credentials>;
+    /**
+     * Throws away the encrypted file without opening it.
+     *
+     * The way out for someone who forgot their master password. Without it they
+     * would be stuck on the unlock page for good, because nothing anywhere can
+     * decrypt that file. What is destroyed is a Bridge password that can be
+     * looked up in the Bridge again, so this is recoverable in the only sense
+     * that matters.
+     */
+    discardEncrypted(): Promise<void>;
+    /**
+     * Stores credentials and marks the session as signed in.
+     *
+     * The caller has already verified them against the Bridge: storing something
+     * that does not work would be worse than not storing it.
+     */
+    signIn(credentials: Credentials, storeKind: StoreKind, 
+    /** Required for the encrypted file, meaningless for every other store. */
+    masterPassword?: string): Promise<void>;
+    /** Forgets the credentials everywhere they might be. */
+    signOut(): Promise<void>;
+    /** Replaces a store. Used by tests and by the startup wiring. */
+    setStore(kind: StoreKind, store: CredentialStore): void;
+}