@atomicmail/mcp 0.1.0 → 0.2.0

package/esm/mcp/src/auth-session.js

@@ -1,378 +0,0 @@
-// AuthSession — stateful PoW + capability JWT manager for the MCP server.
-//
-// Mirrors the protocol implemented in skill/scripts/lib/auth.ts (the
-// @atomic-mail/agent-skill CLIs) and uses the same on-disk layout
-// (credentials.json + session.jwt + capability.jwt) so the MCP and the skill
-// CLIs can share a single credential directory.
-//
-// Tools call session.getCapabilityToken() before every JMAP request. The
-// session manager:
-//
-//   • Decodes JWT exp claims to detect impending expiry.
-//   • Re-runs the full PoW + /api/v1/session handshake when the session JWT
-//     is missing or near expiry.
-//   • Refreshes the capability JWT via /api/v1/capability when it is missing
-//     or near expiry.
-//   • Persists rotated tokens to disk so a restarted MCP process (or a
-//     concurrent atomic-mail-jmap CLI invocation) sees the latest values.
-import process from "node:process";
-import { scrypt } from "node:crypto";
-import { DEFAULT_POW_SCRYPT_SALT_HEX } from "../../lib/src/consts.js";
-import { defaultFilesFromOutDir, tryReadCredentials, tryReadJwtFile, writeCredentials, writeJwtFile, } from "./credentials.js";
-// ── PoW + JWT primitives (mirror skill/scripts/lib/auth.ts) ────────────────
-const SCRYPT_PARAMS = { N: 16384, r: 8, p: 1 };
-const POW_HASH_BYTES = 64;
-export const SESSION_TTL_MS = 4 * 60 * 60 * 1000;
-export const CAPABILITY_TTL_MS = 2 * 60 * 1000;
-// Refresh window: how close to expiry before we re-issue. Server-side TTL is
-// strict so we rotate before the wire-side deadline.
-export const SESSION_SAFETY_MARGIN_MS = 60_000;
-export const CAPABILITY_SAFETY_MARGIN_MS = 20_000;
-export function decodeJwtPayload(jwt) {
-    const parts = jwt.split(".");
-    if (parts.length < 2) {
-        throw new Error("Malformed JWT: expected at least 2 dot-separated segments.");
-    }
-    const payloadB64Url = parts[1];
-    const padLen = (4 - (payloadB64Url.length % 4)) % 4;
-    const base64 = payloadB64Url
-        .replace(/-/g, "+")
-        .replace(/_/g, "/")
-        .padEnd(payloadB64Url.length + padLen, "=");
-    return JSON.parse(atob(base64));
-}
-export function isJwtExpired(jwt, marginMs) {
-    try {
-        const { exp } = decodeJwtPayload(jwt);
-        if (typeof exp !== "number")
-            return true;
-        return Date.now() >= exp * 1000 - marginMs;
-    }
-    catch {
-        return true;
-    }
-}
-function bytesToHex(bytes) {
-    let hex = "";
-    for (let i = 0; i < bytes.length; i++) {
-        hex += bytes[i].toString(16).padStart(2, "0");
-    }
-    return hex;
-}
-function hasLeadingZeroBits(hash, bits) {
-    if (bits > hash.length * 8)
-        return false;
-    const fullBytes = Math.floor(bits / 8);
-    const remainingBits = bits % 8;
-    for (let i = 0; i < fullBytes; i++) {
-        if (hash[i] !== 0)
-            return false;
-    }
-    if (remainingBits > 0) {
-        const mask = (0xff << (8 - remainingBits)) & 0xff;
-        if ((hash[fullBytes] & mask) !== 0)
-            return false;
-    }
-    return true;
-}
-// auth-service feeds the SCRYPT_SALT_HEX string directly to node:crypto's
-// scrypt as the `salt` argument (i.e. the UTF-8 bytes of the hex string,
-// NOT the decoded hex bytes). We mirror that so client and server derive
-// the same digest.
-function scryptHash(data, salt) {
-    const bytes = new TextEncoder().encode(data);
-    return new Promise((resolve, reject) => {
-        scrypt(bytes, salt, POW_HASH_BYTES, SCRYPT_PARAMS, (err, derived) => {
-            if (err)
-                return reject(err);
-            resolve(new Uint8Array(derived));
-        });
-    });
-}
-async function solvePow(challenge, difficulty, salt) {
-    let nonce = 0n;
-    while (true) {
-        const digest = await scryptHash(`${challenge}:${nonce}`, salt);
-        if (hasLeadingZeroBits(digest, difficulty)) {
-            return { powHex: bytesToHex(digest), nonce: nonce.toString() };
-        }
-        nonce++;
-    }
-}
-async function postJson(url, body, headers = {}) {
-    const res = await fetch(url, {
-        method: "POST",
-        headers: {
-            ...(body ? { "Content-Type": "application/json" } : {}),
-            ...headers,
-        },
-        body: body ? JSON.stringify(body) : undefined,
-    });
-    const text = await res.text();
-    const path = (() => {
-        try {
-            return new URL(url).pathname;
-        }
-        catch {
-            return url;
-        }
-    })();
-    if (!res.ok) {
-        throw new Error(`auth-service ${path} returned ${res.status}: ${text}`);
-    }
-    try {
-        return JSON.parse(text);
-    }
-    catch {
-        throw new Error(`auth-service ${path} returned non-JSON body: ${text}`);
-    }
-}
-async function fetchChallenge(authUrl) {
-    const data = await postJson(`${authUrl}/api/v1/challenge`, undefined);
-    if (typeof data.challengeJWT !== "string") {
-        throw new Error("Challenge response missing challengeJWT.");
-    }
-    const payload = decodeJwtPayload(data.challengeJWT);
-    if (typeof payload.jti !== "string" ||
-        typeof payload.difficulty !== "number") {
-        throw new Error("Challenge JWT payload malformed (missing jti or difficulty).");
-    }
-    return {
-        challengeJWT: data.challengeJWT,
-        challenge: payload.jti,
-        difficulty: payload.difficulty,
-    };
-}
-async function exchangeSession(authUrl, body) {
-    const data = await postJson(`${authUrl}/api/v1/session`, { ...body });
-    if (typeof data.sessionJWT !== "string") {
-        throw new Error("Session response missing sessionJWT.");
-    }
-    return {
-        sessionJWT: data.sessionJWT,
-        apiKey: typeof data.apiKey === "string" ? data.apiKey : undefined,
-    };
-}
-async function fetchCapabilityJwt(authUrl, sessionJWT) {
-    const data = await postJson(`${authUrl}/api/v1/capability`, undefined, { Authorization: `Bearer ${sessionJWT}` });
-    if (typeof data.capabilityJWT !== "string") {
-        throw new Error("Capability response missing capabilityJWT.");
-    }
-    return data.capabilityJWT;
-}
-async function performPoWAndSession(input) {
-    const { challengeJWT, challenge, difficulty } = await fetchChallenge(input.authUrl);
-    const { powHex, nonce } = await solvePow(challenge, difficulty, input.scryptSalt);
-    return exchangeSession(input.authUrl, {
-        challengeJWT,
-        powHex,
-        nonce,
-        apiKey: input.apiKey,
-        username: input.username,
-    });
-}
-/**
- * Resolve credential directory from (in priority order):
- *   1. ATOMIC_MAIL_CREDENTIALS_DIR env var
- *   2. ~/.atomicmail/ (POSIX) or %USERPROFILE%/.atomicmail (Windows)
- */
-export function resolveCredentialDir() {
-    const fromEnv = process.env.ATOMIC_MAIL_CREDENTIALS_DIR;
-    if (fromEnv && fromEnv.length > 0)
-        return fromEnv;
-    const home = process.env.HOME || process.env.USERPROFILE;
-    if (!home) {
-        throw new Error("Cannot determine default credential directory: HOME and USERPROFILE " +
-            "are both unset. Set ATOMIC_MAIL_CREDENTIALS_DIR explicitly.");
-    }
-    return `${home.replace(/[\\/]+$/, "")}/.atomicmail`;
-}
-/**
- * Resolve server configuration from:
- *   1. credentials.json in the credential directory (if present and valid).
- *   2. ATOMIC_MAIL_* environment variables (overlay on top of (1) so env
- *      always wins on a per-field basis).
- *
- * The auth and api base URLs MUST be resolvable from at least one source.
- * PoW scrypt salt defaults to the deployment constant when not set in env or
- * credentials.json.
- * The api key is optional; without it, the agent must call the register tool
- * before any JMAP request.
- */
-export async function resolveConfig() {
-    const credentialDir = resolveCredentialDir();
-    const files = defaultFilesFromOutDir(credentialDir);
-    const fileCreds = await tryReadCredentials(files.credentialsFile);
-    const env = process.env;
-    const envAuthUrl = env.ATOMIC_MAIL_AUTH_URL;
-    const envApiUrl = env.ATOMIC_MAIL_API_URL;
-    const envSalt = env.ATOMIC_MAIL_SCRYPT_SALT;
-    const envApiKey = env.ATOMIC_MAIL_API_KEY;
-    const authUrl = envAuthUrl ?? fileCreds?.authUrl;
-    const apiUrl = envApiUrl ?? fileCreds?.apiUrl;
-    const scryptSalt = envSalt ?? fileCreds?.scryptSalt ??
-        DEFAULT_POW_SCRYPT_SALT_HEX;
-    const apiKey = envApiKey ?? fileCreds?.apiKey;
-    const inboxId = fileCreds?.inboxId;
-    const missing = [];
-    if (!authUrl)
-        missing.push("ATOMIC_MAIL_AUTH_URL");
-    if (!apiUrl)
-        missing.push("ATOMIC_MAIL_API_URL");
-    if (missing.length > 0) {
-        throw new Error(`Missing required configuration: ${missing.join(", ")}. ` +
-            `Provide these via environment variables, or place a populated ` +
-            `credentials.json in '${credentialDir}' (run atomic-mail-signup ` +
-            `first, or set ATOMIC_MAIL_CREDENTIALS_DIR to point at an existing ` +
-            `credential directory).`);
-    }
-    const usingFile = fileCreds !== undefined;
-    const usingEnv = !!(envAuthUrl || envApiUrl || envSalt || envApiKey);
-    const source = usingFile && usingEnv
-        ? "mixed"
-        : usingFile
-            ? "credentials-file"
-            : usingEnv
-                ? "env"
-                : "incomplete";
-    return {
-        authUrl: authUrl.replace(/\/+$/, ""),
-        apiUrl: apiUrl.replace(/\/+$/, ""),
-        scryptSalt: scryptSalt,
-        apiKey,
-        inboxId,
-        credentialDir,
-        files,
-        source,
-    };
-}
-export class AuthSession {
-    authUrl;
-    apiUrl;
-    scryptSalt;
-    apiKey;
-    inboxId;
-    credentialDir;
-    files;
-    sessionJWT;
-    capabilityJWT;
-    constructor(cfg) {
-        this.authUrl = cfg.authUrl.replace(/\/+$/, "");
-        this.apiUrl = cfg.apiUrl.replace(/\/+$/, "");
-        this.scryptSalt = cfg.scryptSalt;
-        this.apiKey = cfg.apiKey;
-        this.inboxId = cfg.inboxId;
-        this.credentialDir = cfg.credentialDir;
-        this.files = cfg.files;
-    }
-    /** Construct a session and load any previously persisted JWTs from disk. */
-    static async create(cfg) {
-        const session = new AuthSession(cfg);
-        await session.loadFromDisk();
-        return session;
-    }
-    get hasApiKey() {
-        return this.apiKey !== undefined && this.apiKey.length > 0;
-    }
-    get currentInboxId() {
-        return this.inboxId;
-    }
-    async loadFromDisk() {
-        this.sessionJWT = await tryReadJwtFile(this.files.sessionFile);
-        this.capabilityJWT = await tryReadJwtFile(this.files.capabilityFile);
-    }
-    /**
-     * Full PoW signup. Persists credentials.json + session.jwt + capability.jwt
-     * to disk and updates in-memory state. Throws if an API key is already
-     * configured (refuse to clobber an existing account).
-     */
-    async signup(username) {
-        if (this.hasApiKey) {
-            throw new Error("An API key is already configured. Refusing to overwrite an " +
-                "existing account; remove credentials.json (or unset " +
-                "ATOMIC_MAIL_API_KEY) before registering a new one.");
-        }
-        const result = await performPoWAndSession({
-            authUrl: this.authUrl,
-            scryptSalt: this.scryptSalt,
-            username,
-        });
-        if (!result.apiKey) {
-            throw new Error("Signup did not return an API key — this indicates a server bug.");
-        }
-        this.apiKey = result.apiKey;
-        this.sessionJWT = result.sessionJWT;
-        await writeJwtFile(this.files.sessionFile, this.sessionJWT);
-        const capability = await fetchCapabilityJwt(this.authUrl, this.sessionJWT);
-        this.capabilityJWT = capability;
-        await writeJwtFile(this.files.capabilityFile, capability);
-        const claims = decodeJwtPayload(capability);
-        if (typeof claims.inboxId !== "string" || claims.inboxId.length === 0) {
-            throw new Error("Capability JWT missing inboxId claim after signup.");
-        }
-        this.inboxId = claims.inboxId;
-        const creds = {
-            apiKey: this.apiKey,
-            inboxId: this.inboxId,
-            authUrl: this.authUrl,
-            apiUrl: this.apiUrl,
-            scryptSalt: this.scryptSalt,
-        };
-        await writeCredentials(this.files.credentialsFile, creds);
-        return { apiKey: this.apiKey, inboxId: this.inboxId };
-    }
-    /**
-     * Get a valid capability JWT, rotating session/capability tokens as needed.
-     * This is the primary method tool handlers call before every JMAP request.
-     */
-    async getCapabilityToken() {
-        if (this.capabilityJWT &&
-            !isJwtExpired(this.capabilityJWT, CAPABILITY_SAFETY_MARGIN_MS)) {
-            return this.capabilityJWT;
-        }
-        await this.ensureSession();
-        if (!this.sessionJWT) {
-            throw new Error("Internal: ensureSession() left sessionJWT unset.");
-        }
-        const cap = await fetchCapabilityJwt(this.authUrl, this.sessionJWT);
-        this.capabilityJWT = cap;
-        await writeJwtFile(this.files.capabilityFile, cap);
-        // Capability also carries the canonical inboxId — refresh our cached copy
-        // so the agent always has the latest value via currentInboxId.
-        try {
-            const claims = decodeJwtPayload(cap);
-            if (typeof claims.inboxId === "string" && claims.inboxId.length > 0) {
-                this.inboxId = claims.inboxId;
-            }
-        }
-        catch {
-            // Non-fatal: capability is still usable as a Bearer token.
-        }
-        return cap;
-    }
-    async ensureSession() {
-        if (this.sessionJWT &&
-            !isJwtExpired(this.sessionJWT, SESSION_SAFETY_MARGIN_MS)) {
-            return;
-        }
-        if (!this.apiKey) {
-            throw new Error("No API key configured and no valid session on disk. Either call " +
-                "the 'register' tool to create a new account, set ATOMIC_MAIL_API_KEY, " +
-                "or place a credentials.json into the credential directory.");
-        }
-        const result = await performPoWAndSession({
-            authUrl: this.authUrl,
-            scryptSalt: this.scryptSalt,
-            apiKey: this.apiKey,
-        });
-        this.sessionJWT = result.sessionJWT;
-        // After session rotation, the previous capability is no longer recognized
-        // by auth-service (challenge cache reset), so force a refresh next.
-        this.capabilityJWT = undefined;
-        await writeJwtFile(this.files.sessionFile, this.sessionJWT);
-    }
-    /** Clean shutdown. No-op today; reserved for future cleanup. */
-    destroy() {
-        // Nothing to clean up — all state is on disk + in-memory only.
-    }
-}

package/esm/mcp/src/credentials.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../../../src/mcp/src/credentials.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAOjE;AAMD,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC,IAAI,CAAC,CAGf;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAiCxE;AAED,gFAAgF;AAChF,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAOlC;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG3E;AAED,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAO7B"}

package/esm/mcp/src/docs-content.d.ts

@@ -1,4 +0,0 @@
-export declare const TOPICS: Record<string, string>;
-export declare const TOPIC_LIST: string[];
-export declare function getDocs(topic?: string): string;
-//# sourceMappingURL=docs-content.d.ts.map

package/esm/mcp/src/docs-content.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"docs-content.d.ts","sourceRoot":"","sources":["../../../src/mcp/src/docs-content.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA+YzC,CAAC;AAEF,eAAO,MAAM,UAAU,UAAsB,CAAC;AAE9C,wBAAgB,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAS9C"}