@rndmjoker/proton-mcp 0.4.4

package/dist/web/security.d.ts

@@ -0,0 +1,122 @@
+/**
+ * The security layer of the local web interface.
+ *
+ * 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.
+ *
+ * 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.
+ * 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
+ *    Host other than a loopback name stops it. This is DNS rebinding, and it is
+ *    the attack local servers most often forget.
+ * 3. **Origin check plus CSRF token on writes.** A page from elsewhere can post
+ *    a form to 127.0.0.1 without reading the response. That is enough to change
+ *    settings, so writes require a matching origin and a token bound to the
+ *    session.
+ * 4. **A restrictive Content-Security-Policy.** No external scripts, styles,
+ *    fonts or images, and no inline event handlers, so injected markup cannot
+ *    fetch anything or run.
+ *
+ * All comparisons of secrets use timingSafeEqual, so response time does not
+ * reveal how much of a token was right.
+ */
+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;
+/** Compares two secrets without leaking their similarity through timing. */
+export declare function safeEqual(a: string, b: string): boolean;
+/**
+ * Checks the Host header.
+ *
+ * The defence against DNS rebinding: a page at evil.example.com can point that
+ * name at 127.0.0.1, and the browser will happily send requests with
+ * `Host: evil.example.com`. Only loopback names are accepted.
+ */
+export declare function isAllowedHost(host: string | undefined): boolean;
+/**
+ * Checks the Origin header for state-changing requests.
+ *
+ * A missing Origin is accepted, because browsers omit it for ordinary top-level
+ * navigation and non-browser clients never send it. A present but foreign one is
+ * rejected: that is a cross-site request.
+ */
+export declare function isAllowedOrigin(origin: string | undefined, port: number): boolean;
+/**
+ * Derives a CSRF token for a form.
+ *
+ * Bound to the session secret and to the form's purpose, so a token for one
+ * action cannot be replayed against another.
+ */
+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 interface CheckResult {
+    ok: boolean;
+    reason?: RejectionReason;
+}
+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. */
+    csrf?: {
+        purpose: string;
+        presented: string | undefined;
+    };
+}
+/**
+ * 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.
+ */
+export declare function checkRequest(options: CheckOptions): CheckResult;
+/**
+ * The referrer policy.
+ *
+ * `same-origin` rather than the stricter-looking `no-referrer`, and this is not a
+ * concession: `no-referrer` **breaks the Origin check above**, which makes every
+ * form on this interface unusable.
+ *
+ * The mechanism, per the Fetch standard: when a request's referrer policy is
+ * `no-referrer`, the browser sets the request's origin to an opaque one, and the
+ * `Origin` header goes out as the literal string `null`. Since a foreign or
+ * sandboxed page can also produce `Origin: null`, that value has to be refused,
+ * so the interface would refuse its own forms. Confirmed in a real browser:
+ * every POST answered 404 with reason `bad-origin` until this was changed.
+ *
+ * Nothing is given up. The strict CSP already forbids this page from reaching any
+ * other host, and the page contains no external links, so `same-origin` has no
+ * third party to leak a referrer to in the first place.
+ *
+ * Do not "harden" this back to `no-referrer` without a browser to try it in.
+ */
+export declare const REFERRER_POLICY = "same-origin";
+/**
+ * The headers every response carries.
+ *
+ * The CSP is the strict kind: nothing may be loaded from anywhere, styles are
+ * allowed only from the document itself, and there is no way to reach the
+ * network. `frame-ancestors 'none'` keeps the page out of foreign frames, which
+ * also rules out clickjacking.
+ */
+export declare function securityHeaders(): Record<string, string>;

package/dist/web/security.js

@@ -0,0 +1,180 @@
+/**
+ * The security layer of the local web interface.
+ *
+ * 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.
+ *
+ * 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.
+ * 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
+ *    Host other than a loopback name stops it. This is DNS rebinding, and it is
+ *    the attack local servers most often forget.
+ * 3. **Origin check plus CSRF token on writes.** A page from elsewhere can post
+ *    a form to 127.0.0.1 without reading the response. That is enough to change
+ *    settings, so writes require a matching origin and a token bound to the
+ *    session.
+ * 4. **A restrictive Content-Security-Policy.** No external scripts, styles,
+ *    fonts or images, and no inline event handlers, so injected markup cannot
+ *    fetch anything or run.
+ *
+ * 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';
+/** 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'),
+    };
+}
+/** Compares two secrets without leaking their similarity through timing. */
+export function safeEqual(a, b) {
+    const left = Buffer.from(a, 'utf8');
+    const right = Buffer.from(b, 'utf8');
+    // timingSafeEqual throws on differing lengths, which would itself be a signal,
+    // so pad to a fixed size first.
+    const size = Math.max(left.length, right.length, 1);
+    const paddedLeft = Buffer.alloc(size);
+    const paddedRight = Buffer.alloc(size);
+    left.copy(paddedLeft);
+    right.copy(paddedRight);
+    return timingSafeEqual(paddedLeft, paddedRight) && left.length === right.length;
+}
+/**
+ * Checks the Host header.
+ *
+ * The defence against DNS rebinding: a page at evil.example.com can point that
+ * name at 127.0.0.1, and the browser will happily send requests with
+ * `Host: evil.example.com`. Only loopback names are accepted.
+ */
+export function isAllowedHost(host) {
+    if (!host)
+        return false;
+    // Strip the port. IPv6 literals keep their brackets.
+    const withoutPort = host.startsWith('[')
+        ? (host.match(/^\[[^\]]+\]/)?.[0] ?? host)
+        : (host.split(':')[0] ?? host);
+    return LOOPBACK_HOSTS.has(withoutPort.toLowerCase());
+}
+/**
+ * Checks the Origin header for state-changing requests.
+ *
+ * A missing Origin is accepted, because browsers omit it for ordinary top-level
+ * navigation and non-browser clients never send it. A present but foreign one is
+ * rejected: that is a cross-site request.
+ */
+export function isAllowedOrigin(origin, port) {
+    if (!origin)
+        return true;
+    if (origin === 'null')
+        return false;
+    let parsed;
+    try {
+        parsed = new URL(origin);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol !== 'http:')
+        return false;
+    if (parsed.port && Number(parsed.port) !== port)
+        return false;
+    return LOOPBACK_HOSTS.has(parsed.hostname.toLowerCase());
+}
+/**
+ * Derives a CSRF token for a form.
+ *
+ * Bound to the session secret and to the form's purpose, so a token for one
+ * action cannot be replayed against another.
+ */
+export function csrfToken(secrets, purpose) {
+    return createHmac('sha256', secrets.csrfSecret).update(purpose).digest('base64url');
+}
+export function csrfValid(secrets, purpose, presented) {
+    return safeEqual(csrfToken(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.
+ */
+export function checkRequest(options) {
+    const { request, secrets, port, presentedToken, 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' };
+        if (!csrf?.presented || !csrfValid(secrets, csrf.purpose, csrf.presented)) {
+            return { ok: false, reason: 'bad-csrf' };
+        }
+    }
+    return { ok: true };
+}
+/**
+ * The referrer policy.
+ *
+ * `same-origin` rather than the stricter-looking `no-referrer`, and this is not a
+ * concession: `no-referrer` **breaks the Origin check above**, which makes every
+ * form on this interface unusable.
+ *
+ * The mechanism, per the Fetch standard: when a request's referrer policy is
+ * `no-referrer`, the browser sets the request's origin to an opaque one, and the
+ * `Origin` header goes out as the literal string `null`. Since a foreign or
+ * sandboxed page can also produce `Origin: null`, that value has to be refused,
+ * so the interface would refuse its own forms. Confirmed in a real browser:
+ * every POST answered 404 with reason `bad-origin` until this was changed.
+ *
+ * Nothing is given up. The strict CSP already forbids this page from reaching any
+ * other host, and the page contains no external links, so `same-origin` has no
+ * third party to leak a referrer to in the first place.
+ *
+ * Do not "harden" this back to `no-referrer` without a browser to try it in.
+ */
+export const REFERRER_POLICY = 'same-origin';
+/**
+ * The headers every response carries.
+ *
+ * The CSP is the strict kind: nothing may be loaded from anywhere, styles are
+ * allowed only from the document itself, and there is no way to reach the
+ * network. `frame-ancestors 'none'` keeps the page out of foreign frames, which
+ * also rules out clickjacking.
+ */
+export function securityHeaders() {
+    return {
+        'Content-Security-Policy': [
+            "default-src 'none'",
+            "style-src 'self' 'unsafe-inline'",
+            "img-src 'self' data:",
+            "form-action 'self'",
+            "frame-ancestors 'none'",
+            "base-uri 'none'",
+        ].join('; '),
+        'X-Content-Type-Options': 'nosniff',
+        'X-Frame-Options': 'DENY',
+        'Referrer-Policy': REFERRER_POLICY,
+        // The interface shows configuration, never mail. Still, nothing here should
+        // linger in a cache a later user could read.
+        'Cache-Control': 'no-store, max-age=0',
+        // No browser feature this page needs is worth leaving enabled.
+        'Permissions-Policy': 'geolocation=(), camera=(), microphone=(), payment=()',
+    };
+}
+//# sourceMappingURL=security.js.map

package/dist/web/security.js.map

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

package/dist/web/server.d.ts

@@ -0,0 +1,153 @@
+/**
+ * The local web interface.
+ *
+ * Built on node:http with no framework. For something that handles credentials,
+ * every dependency is attack surface, and the routing here fits on one screen.
+ *
+ * It serves no files from disk at all: every response is generated. That removes
+ * path traversal as a category rather than guarding against it.
+ *
+ * All security checks live in security.ts and run before any handler. See there
+ * for what each one defends against.
+ */
+import { type IncomingMessage } from 'node:http';
+import type { Credentials, CredentialStore, StoreKind } from '../credentials/store.js';
+/**
+ * The port tried first.
+ *
+ * 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.
+ */
+export declare const DEFAULT_WEB_PORT = 7345;
+/**
+ * How many consecutive ports to try.
+ *
+ * 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.
+ */
+export declare const PORT_ATTEMPTS = 10;
+export interface WebInterfaceOptions {
+    /** 0 lets the operating system pick a free port, which is the default. */
+    port?: number;
+    /**
+     * 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.
+     */
+    onSignIn: (credentials: Credentials, store: StoreKind, masterPassword?: string) => Promise<string | undefined>;
+    /** Called when the user signs out. */
+    onSignOut: () => Promise<void>;
+    /**
+     * Opens an existing encrypted credentials file. Returns an error message to
+     * show, or nothing on success.
+     *
+     * Only reached when getStatus reports locked, so an interface wired without
+     * this cannot get here.
+     */
+    onUnlock?: (masterPassword: string) => Promise<string | undefined>;
+    /** Throws the encrypted file away, for a forgotten master password. */
+    onDiscardEncrypted?: () => Promise<void>;
+    /** Supplies what the status page shows. */
+    getStatus: () => Promise<StatusSnapshot>;
+    /**
+     * Changes the Bridge ports. Returns an error message to show, or nothing.
+     *
+     * Absent when the ports came from the environment, which is what makes the
+     * form disappear rather than fail.
+     */
+    onPorts?: (ports: {
+        imapPort: number;
+        smtpPort: number;
+    }) => Promise<string | undefined>;
+    /** Tries the Bridge. Returns a message either way: this one reports success. */
+    onTest?: () => Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+    /** Lists the mailboxes, for the page that shows them on request. */
+    getMailboxes?: () => Promise<Array<{
+        path: string;
+        kind: 'system' | 'folder' | 'label';
+        selectable: boolean;
+    }>>;
+    /** What is running and what ran, for the activity section. */
+    getActivity?: () => {
+        running: Array<{
+            tool: string;
+            forMs: number;
+        }>;
+        recent: Array<{
+            tool: string;
+            at: number;
+            durationMs: number;
+            outcome: 'ok' | 'failed';
+        }>;
+    };
+    /**
+     * Whether the "not affiliated with Proton" notice was sent away already.
+     *
+     * Absent means it is shown without a way to dismiss it, which is the safe
+     * direction: a legal statement should not vanish because a caller left a
+     * handler out.
+     */
+    noticeDismissed?: () => boolean;
+    /** Remembers a dismissal. Without it the notice has no button. */
+    onDismissNotice?: () => Promise<void>;
+    /** Where notices go. stderr, never stdout, which carries the MCP protocol. */
+    notify?: (message: string) => void;
+}
+/** Everything the status page needs, gathered by the caller. */
+export interface StatusSnapshot {
+    connected: boolean;
+    /**
+     * True when credentials are stored but need a master password first. Leads
+     * to the unlock page instead of the full sign-in form.
+     */
+    locked?: boolean;
+    /** Where the encrypted file is, shown on the unlock page. */
+    encryptedPath?: string;
+    address?: string;
+    storeKind?: StoreKind;
+    mailboxCount?: number;
+    messageCount?: number;
+    unseenCount?: number;
+    certificate?: {
+        fingerprint: string;
+        subject: string;
+        firstSeen: string;
+    };
+    bridgeHost: string;
+    bridgeImapPort: number;
+    /**
+     * Required, not optional. It used to fall back to 0, which is not a port:
+     * the advanced block would prefill a value the same form then refused.
+     */
+    bridgeSmtpPort: number;
+    readOnly?: boolean;
+    uptimeMs?: number;
+}
+interface ParsedBody {
+    fields: Record<string, string>;
+    tooLarge: boolean;
+}
+/**
+ * Reads a form body, refusing anything oversized.
+ *
+ * The limit is enforced while reading rather than after, so an oversized body is
+ * never held in memory in full.
+ */
+export declare function readBody(request: IncomingMessage, maxBytes?: number): Promise<ParsedBody>;
+export declare class WebInterface {
+    #private;
+    constructor(options: WebInterfaceOptions);
+    /** The URL the user has to open, including the access token. */
+    get url(): string;
+    get port(): number;
+    get running(): boolean;
+    start(): Promise<string>;
+    stop(): Promise<void>;
+    /** Invalidates the current link and issues a new one. */
+    rotateToken(): string;
+}
+export type { CredentialStore };