@rndmjoker/proton-mcp 0.4.13 → 0.5.1

package/dist/web/security.d.ts

@@ -3,15 +3,19 @@
  *
  * The threat model is not "someone on the internet": the server binds to
  * loopback only, so nobody reaches it from outside. What has to be defended
- * against is anything else running on the same machine, and anything the user's
- * browser is talked into doing by a page from elsewhere.
+ * against is anything the user's browser is talked into doing by a page from
+ * elsewhere, and, when the user sets one, anything on the same machine that does
+ * not know the PIN.
  *
  * Four defences, each against a specific attack:
  *
- * 1. **A session token in the URL.** Any local program can send a request to
- *    127.0.0.1. Without a secret it could drive the interface, read the state
- *    and store credentials of its choosing. The token is generated per process
- *    and never written to disk.
+ * 1. **An optional PIN on every change.** Any local program can send a request
+ *    to 127.0.0.1, and so can the assistant, through a browser tool. Until
+ *    2026-11-05 a token in the address kept them out, but the address reached
+ *    the assistant through `open_configuration`, so the token protected against
+ *    everything except the one party the switches for autonomy are about. A PIN
+ *    the user types and the assistant never sees does. It is optional: without
+ *    one, anything on this machine can change the settings, and the pages say so.
  * 2. **Host header check.** A page on the internet can resolve its own domain to
  *    127.0.0.1 and have the browser send requests there. The browser then treats
  *    that domain as the origin, so same-origin rules do not help. Rejecting any
@@ -30,13 +34,44 @@
  */
 import type { IncomingMessage } from 'node:http';
 export interface SessionSecrets {
-    /** Grants access at all. Part of the URL the user opens. */
-    accessToken: string;
     /** Signs CSRF tokens. Never leaves the process. */
     csrfSecret: string;
 }
 /** Creates the per-process secrets. */
 export declare function createSession(): SessionSecrets;
+/**
+ * A PIN as it is stored: salted and run through scrypt, never the PIN itself.
+ *
+ * The settings file is readable by the user's own programs, the assistant
+ * included when it can read files. A plain PIN there would be a PIN the
+ * assistant can look up. A hash of a short PIN can still be guessed offline,
+ * which is why the length rule below asks for more than four digits and why
+ * scrypt rather than a fast hash: every guess has to pay for the memory.
+ */
+export interface StoredPin {
+    salt: string;
+    hash: string;
+}
+/** Why a PIN cannot be used, or nothing when it can. */
+export declare function pinProblem(pin: string): string | undefined;
+export declare function hashPin(pin: string): Promise<StoredPin>;
+export declare function pinMatches(pin: string, stored: StoredPin): Promise<boolean>;
+/**
+ * Slows down guessing.
+ *
+ * After `max` wrong PINs within `windowMs`, every attempt is refused until the
+ * window has passed, the right PIN included: a lock that the right answer opens
+ * early tells the guesser when they found it. Held in memory by the server that
+ * shows the interface, which is the only one that checks PINs.
+ */
+export declare class AttemptLimiter {
+    #private;
+    constructor(max?: number, windowMs?: number);
+    /** Whether an attempt may be checked at all right now. */
+    allowed(now?: number): boolean;
+    fail(now?: number): void;
+    reset(): void;
+}
 /** Compares two secrets without leaking their similarity through timing. */
 export declare function safeEqual(a: string, b: string): boolean;
 /**
@@ -64,7 +99,7 @@ export declare function isAllowedOrigin(origin: string | undefined, port: number
 export declare function csrfToken(secrets: SessionSecrets, purpose: string): string;
 export declare function csrfValid(secrets: SessionSecrets, purpose: string, presented: string): boolean;
 /** Why a request was rejected. Deliberately vague towards the client. */
-export type RejectionReason = 'bad-host' | 'bad-origin' | 'bad-token' | 'bad-csrf' | 'method-not-allowed';
+export type RejectionReason = 'bad-host' | 'bad-origin' | 'bad-csrf' | 'method-not-allowed';
 export interface CheckResult {
     ok: boolean;
     reason?: RejectionReason;
@@ -73,8 +108,6 @@ export interface CheckOptions {
     request: IncomingMessage;
     secrets: SessionSecrets;
     port: number;
-    /** The token presented by the client, from the query string or a header. */
-    presentedToken: string | undefined;
     /** True for requests that change something. */
     writing: boolean;
     /** For writing requests: the CSRF token and what it is for. */
@@ -86,8 +119,10 @@ export interface CheckOptions {
 /**
  * Runs every check in order.
  *
- * Order matters: the host check comes before the token check, so a rebinding
- * attempt is refused before it can even try tokens.
+ * Order matters: the host check comes first, so a rebinding attempt is refused
+ * before anything else is looked at. The PIN is not checked here: a wrong PIN is
+ * the user's mistake and gets a page that says so, where every failure in here
+ * gets the same refusal that says nothing.
  */
 export declare function checkRequest(options: CheckOptions): CheckResult;
 /**

package/dist/web/security.js

@@ -3,15 +3,19 @@
  *
  * The threat model is not "someone on the internet": the server binds to
  * loopback only, so nobody reaches it from outside. What has to be defended
- * against is anything else running on the same machine, and anything the user's
- * browser is talked into doing by a page from elsewhere.
+ * against is anything the user's browser is talked into doing by a page from
+ * elsewhere, and, when the user sets one, anything on the same machine that does
+ * not know the PIN.
  *
  * Four defences, each against a specific attack:
  *
- * 1. **A session token in the URL.** Any local program can send a request to
- *    127.0.0.1. Without a secret it could drive the interface, read the state
- *    and store credentials of its choosing. The token is generated per process
- *    and never written to disk.
+ * 1. **An optional PIN on every change.** Any local program can send a request
+ *    to 127.0.0.1, and so can the assistant, through a browser tool. Until
+ *    2026-11-05 a token in the address kept them out, but the address reached
+ *    the assistant through `open_configuration`, so the token protected against
+ *    everything except the one party the switches for autonomy are about. A PIN
+ *    the user types and the assistant never sees does. It is optional: without
+ *    one, anything on this machine can change the settings, and the pages say so.
  * 2. **Host header check.** A page on the internet can resolve its own domain to
  *    127.0.0.1 and have the browser send requests there. The browser then treats
  *    that domain as the origin, so same-origin rules do not help. Rejecting any
@@ -28,18 +32,67 @@
  * All comparisons of secrets use timingSafeEqual, so response time does not
  * reveal how much of a token was right.
  */
-import { randomBytes, timingSafeEqual, createHmac } from 'node:crypto';
+import { randomBytes, timingSafeEqual, createHmac, scrypt } from 'node:crypto';
 /** Hostnames that mean this machine. Anything else is rejected. */
 const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '[::1]', '::1']);
 /** Creates the per-process secrets. */
 export function createSession() {
     return {
-        // 32 bytes base64url: long enough that guessing is hopeless, short enough
-        // to survive being copied into a browser.
-        accessToken: randomBytes(32).toString('base64url'),
         csrfSecret: randomBytes(32).toString('base64url'),
     };
 }
+/** scrypt with Node's default cost, named so a change here is deliberate. */
+const PIN_KEY_LENGTH = 32;
+const PIN_COST = { N: 16384, r: 8, p: 1 };
+function derive(pin, salt) {
+    return new Promise((resolve, reject) => {
+        scrypt(pin.normalize('NFC'), salt, PIN_KEY_LENGTH, PIN_COST, (error, key) => error ? reject(error) : resolve(key));
+    });
+}
+/** Why a PIN cannot be used, or nothing when it can. */
+export function pinProblem(pin) {
+    if (pin.length < 6)
+        return 'The PIN needs at least 6 characters.';
+    if (pin.length > 128)
+        return 'The PIN can have at most 128 characters.';
+    return undefined;
+}
+export async function hashPin(pin) {
+    const salt = randomBytes(16).toString('base64url');
+    return { salt, hash: (await derive(pin, salt)).toString('base64url') };
+}
+export async function pinMatches(pin, stored) {
+    const presented = await derive(pin, stored.salt);
+    return safeEqual(presented.toString('base64url'), stored.hash);
+}
+/**
+ * Slows down guessing.
+ *
+ * After `max` wrong PINs within `windowMs`, every attempt is refused until the
+ * window has passed, the right PIN included: a lock that the right answer opens
+ * early tells the guesser when they found it. Held in memory by the server that
+ * shows the interface, which is the only one that checks PINs.
+ */
+export class AttemptLimiter {
+    #failures = [];
+    #max;
+    #windowMs;
+    constructor(max = 5, windowMs = 60_000) {
+        this.#max = max;
+        this.#windowMs = windowMs;
+    }
+    /** Whether an attempt may be checked at all right now. */
+    allowed(now = Date.now()) {
+        this.#failures = this.#failures.filter((at) => now - at < this.#windowMs);
+        return this.#failures.length < this.#max;
+    }
+    fail(now = Date.now()) {
+        this.#failures.push(now);
+    }
+    reset() {
+        this.#failures = [];
+    }
+}
 /** Compares two secrets without leaking their similarity through timing. */
 export function safeEqual(a, b) {
     const left = Buffer.from(a, 'utf8');
@@ -109,16 +162,15 @@ export function csrfValid(secrets, purpose, presented) {
 /**
  * Runs every check in order.
  *
- * Order matters: the host check comes before the token check, so a rebinding
- * attempt is refused before it can even try tokens.
+ * Order matters: the host check comes first, so a rebinding attempt is refused
+ * before anything else is looked at. The PIN is not checked here: a wrong PIN is
+ * the user's mistake and gets a page that says so, where every failure in here
+ * gets the same refusal that says nothing.
  */
 export function checkRequest(options) {
-    const { request, secrets, port, presentedToken, writing, csrf } = options;
+    const { request, secrets, port, writing, csrf } = options;
     if (!isAllowedHost(request.headers.host))
         return { ok: false, reason: 'bad-host' };
-    if (!presentedToken || !safeEqual(secrets.accessToken, presentedToken)) {
-        return { ok: false, reason: 'bad-token' };
-    }
     if (writing) {
         if (!isAllowedOrigin(request.headers.origin, port))
             return { ok: false, reason: 'bad-origin' };

package/dist/web/security.js.map

@@ -1 +1 @@
-{"version":3,"file":"security.js","sourceRoot":"","sources":["../../src/web/security.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"security.js","sourceRoot":"","sources":["../../src/web/security.ts"],"names":[],"mappings":"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"}

package/dist/web/server.d.ts

@@ -12,30 +12,68 @@
  */
 import { type IncomingMessage } from 'node:http';
 import type { Credentials, CredentialStore, StoreKind } from '../credentials/store.js';
-import { type PendingData } from './pending.js';
+import { type StoredPin } from './security.js';
+import { type ServerSummary, type ToolLevelView, type LimitsView, type RecordView, type FilterActionsView } from './sections.js';
+import type { Level, SendLimits, RecordCopy } from '../settings.js';
+import { type Unlockable } from '../filters/sieve.js';
 /**
- * The port tried first.
+ * The one address of the interface, shared by every running server.
  *
- * A fixed default rather than a random one, because the interface runs for as
- * long as the server does and is meant to be opened again and again. A port that
- * moved on every start would make that needlessly awkward.
+ * Fixed rather than random, and since 2026-11-05 also not walked upwards when
+ * taken: every client session starts its own server, and the interface they
+ * share has to be at the same address for all of them. The first server to
+ * start serves it; the others take over when it stops.
  */
 export declare const DEFAULT_WEB_PORT = 7345;
+/** How often a server that does not serve the interface tries to take it over. */
+export declare const TAKEOVER_INTERVAL_MS = 10000;
 /**
- * How many consecutive ports to try.
+ * Who is on the port: another proton-mcp, an older one, something else, or
+ * nobody.
  *
- * Several clients may each start their own server, and the second one must not
- * fail over a port the first one took. Failing outright would be worse than
- * moving up by one.
+ * "older" is a proton-mcp from before the shared interface, 0.4 and earlier.
+ * Each of those served an interface of its own, with a token in the address,
+ * and knows nothing of the others. One still running in a session started
+ * before an update holds the port until that session ends.
  */
-export declare const PORT_ATTEMPTS = 10;
+export type PortOccupant = 'proton-mcp' | 'older' | 'other' | 'none';
 export interface WebInterfaceOptions {
     /**
-     * Left out, the interface starts at DEFAULT_WEB_PORT and walks upwards past
-     * anything already listening. 0 lets the operating system pick a free port,
-     * which the tests use to avoid collisions; it is not the default.
+     * Left out, the interface uses DEFAULT_WEB_PORT. 0 lets the operating system
+     * pick a free port, which the tests use to avoid collisions; there is no
+     * takeover then, since no other server could know the address.
      */
     port?: number;
+    /** The PIN as stored, or nothing while none is set. Read on every request. */
+    getPin?: () => StoredPin | undefined;
+    /** Stores a new PIN, or removes it with undefined. Returns an error to show. */
+    onPinChange?: (next: StoredPin | undefined) => Promise<string | undefined>;
+    /** Every running server, for the overview. */
+    getServers?: () => ServerSummary[];
+    /** Told whenever this server starts or stops serving the interface. */
+    onServingChange?: (serving: boolean) => void;
+    /** How often to try taking over the port. TAKEOVER_INTERVAL_MS unless a test says otherwise. */
+    takeoverIntervalMs?: number;
+    /** What each tool may do and the bounds on sending without asking, for the permissions page. */
+    getPermissions?: () => {
+        tools: ToolLevelView[];
+        limits: LimitsView;
+    };
+    /**
+     * Stores the levels chosen on the page, only those not fixed by the
+     * environment. Returns an error to show, or nothing.
+     */
+    onLevels?: (levels: Record<string, Level>) => Promise<string | undefined>;
+    /** Stores the bounds on sending without asking. Returns an error to show, or nothing. */
+    onLimits?: (limits: SendLimits) => Promise<string | undefined>;
+    /** The recipient added to every message sent, for the pages. */
+    getRecord?: () => RecordView;
+    /** Stores it, or removes it with undefined. Returns an error to show, or nothing. */
+    onRecord?: (record: RecordCopy | undefined) => Promise<string | undefined>;
+    /** What a filter from an assistant may do beyond filing and flags, for the pages. */
+    getFilterActions?: () => FilterActionsView;
+    /** Stores it. Returns an error to show, or nothing. */
+    onFilterActions?: (actions: Unlockable[]) => Promise<string | undefined>;
     /**
      * Called when the user signs in. Returns an error message to show, or nothing
      * on success. The master password is only set for the encrypted-file store.
@@ -110,14 +148,6 @@ export interface WebInterfaceOptions {
     noticeDismissed?: () => boolean;
     /** Remembers a dismissal. Without it the notice has no button. */
     onDismissNotice?: () => Promise<void>;
-    /**
-     * The message behind a pending confirmation, if one is waiting.
-     *
-     * Absent when nothing can be previewed, which makes the page say so rather
-     * than fail. What it returns is decrypted mail, so the caller holds it in
-     * memory only and drops it as soon as the question is answered.
-     */
-    getPending?: (digest: string) => Omit<PendingData, 'token' | 'disclaimer'> | undefined;
     /** Where notices go. stderr, never stdout, which carries the MCP protocol. */
     notify?: (message: string) => void;
 }
@@ -165,13 +195,40 @@ export declare function readBody(request: IncomingMessage, maxBytes?: number): P
 export declare class WebInterface {
     #private;
     constructor(options: WebInterfaceOptions);
-    /** The URL the user has to open, including the access token. */
+    /**
+     * The address of the interface. The same for every running server, whichever
+     * of them serves it, and nothing in it is secret.
+     */
     get url(): string;
     get port(): number;
+    /** True while this server serves the interface itself. */
     get running(): boolean;
+    /**
+     * Whether the interface can be reached at `url`, from this server or from
+     * another running proton-mcp. False when something else holds the port.
+     */
+    get reachable(): boolean;
+    /** Who held the port when this server last found it taken. */
+    get occupant(): PortOccupant;
+    /**
+     * Asks whoever holds the port whether it is a proton-mcp.
+     *
+     * The answer decides between "another session serves the interface, all is
+     * well" and "something else sits on this port", which the user has to hear
+     * about, because then nobody serves the interface at all. An older proton-mcp
+     * is the third answer: no interface either, but the remedy is to restart the
+     * sessions that still run it, not to move every server to another port.
+     */
+    static probe(port: number, timeoutMs?: number): Promise<PortOccupant>;
+    /**
+     * Serves the interface, or leaves it to the server that already does.
+     *
+     * Never throws over a taken port. Another proton-mcp on it is the ordinary
+     * case with several sessions; this server then tries every few seconds to
+     * take over, so the interface survives the session that started it. Anything
+     * else on the port is reported once, and taken over too if it ever leaves.
+     */
     start(): Promise<string>;
     stop(): Promise<void>;
-    /** Invalidates the current link and issues a new one. */
-    rotateToken(): string;
 }
 export type { CredentialStore };