wazap-mcp 0.9.8 → 0.10.0

package/README.md

@@ -8,7 +8,7 @@
 ```
 
 **WhatsApp for your AI agent.** An MCP server that puts your WhatsApp account —
-chats, messages, media, contacts, groups — behind 23 tools any MCP client can
+chats, messages, media, contacts, groups — behind 24 tools any MCP client can
 call. Pairing-code login, no browser, no phone-number reseller, ~20 MB of RAM.
 
 Built on [Baileys](https://github.com/WhiskeySockets/Baileys), which speaks the
@@ -82,7 +82,7 @@ it would write.
 | `gemini` | `~/.gemini/settings.json` |
 | `windsurf` | `~/.codeium/windsurf/mcp_config.json` |
 | `opencode` | `mcp.whatsapp` in `~/.config/opencode/opencode.json` |
-| anything remote | client's MCP URL field: `https://your-host/mcp` with header `Authorization: Bearer <token>` (see [Self-host](#self-host)) |
+| anything remote | client's MCP URL field: `https://your-host/mcp` with header `Authorization: Bearer <token>`, or just the URL once [OAuth](#hosted-agents-oauth) is on (see [Self-host](#self-host)) |
 
 ### Other MCP clients
 
@@ -363,6 +363,7 @@ created `0700` with credentials written `0600`:
   store.json    chat-list snapshot
   server.lock   pid of the running server
   daemon.json   loopback endpoint a second wazap bridges to
+  oauth.json    registered agents and hashed OAuth grants, when OAuth is on
   .env          optional settings, see .env.example
 ```
 
@@ -413,7 +414,8 @@ npx wazap-mcp serve --http --host 0.0.0.0 --port 8766
 Streamable HTTP at `/mcp`, with a health check at `/healthz`. Two bearer tokens:
 the read token gets the read tools, the write token also unlocks the write
 tools, so a leaked read token can never message anyone. wazap refuses to bind a
-non-loopback address without a read token.
+non-loopback address without a read token. Agents that cannot carry a header
+sign in with [OAuth](#hosted-agents-oauth) instead.
 
 ## Self-host
 
@@ -448,9 +450,63 @@ curl -s http://127.0.0.1:8766/healthz
 
 The container publishes `8766` on loopback only; add the same TLS proxy in front. Upgrading is `git pull && docker compose up -d --build`; the volume keeps the session.
 
+### From a machine without a public address
+
+A laptop or a box behind NAT can still serve hosted agents through a tunnel, with no port opened and TLS done at the edge. With [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) and a domain on Cloudflare:
+
+```bash
+cloudflared tunnel login
+cloudflared tunnel create wazap
+cloudflared tunnel route dns wazap wazap.example.com
+cloudflared tunnel run --url http://127.0.0.1:8766 wazap
+```
+
+wazap keeps binding loopback; only the tunnel reaches it. Set `WAZAP_PUBLIC_URL=https://wazap.example.com` for OAuth and keep `cloudflared` running the way you keep wazap running (a systemd unit, a launchd agent). Tailscale Funnel or ngrok work the same way: whatever ends at `https://your-host` with `/mcp` behind it.
+
 ### Which clients can reach it
 
-Claude Code, Claude Desktop, Cursor, Codex, VS Code and any client with an "MCP URL + header" field connect with the bearer token. claude.ai Connectors require OAuth rather than a static token, so they cannot use a self-hosted wazap yet. Keep the read token in clients that only need to read; hand out the write token deliberately.
+Claude Code, Claude Desktop, Cursor, Codex, VS Code, Poke and any client with an "MCP URL + header" field connect with the bearer token. Keep the read token in clients that only need to read; hand out the write token deliberately.
+
+claude.ai Connectors, ChatGPT and some hosted agents will not take a static header. They want OAuth, which is the next section.
+
+### Hosted agents (OAuth)
+
+Two more lines in the same `.env` turn wazap into its own OAuth 2.1 server:
+
+```bash
+WAZAP_PUBLIC_URL=https://wazap.example.com
+WAZAP_OAUTH_PASSWORD=$(openssl rand -base64 18)
+```
+
+Then give an agent nothing but `https://wazap.example.com/mcp`. It finds the
+authorization server at `/.well-known/oauth-protected-resource/mcp`, registers
+itself (RFC 7591, so there is no client id to paste anywhere), and sends you to
+a page on your own host that asks two things: the password above, and whether
+this agent may only read or also send. A refresh token keeps the agent signed
+in until you revoke it; access tokens rotate every 24 hours on their own.
+
+Tested against the flow claude.ai, ChatGPT and Poke use: S256 PKCE, public
+clients, `/token` with refresh, `/revoke`. The bearer tokens keep working next
+to it, so a laptop client on a header and a hosted agent on OAuth share one
+server.
+
+What to know before exposing it:
+
+- `WAZAP_PUBLIC_URL` must be `https` and a bare origin, no path: the
+  endpoints live at its root. The password travels to it.
+- The password is the whole identity layer. Use a long one. A consent page
+  takes three wrong guesses and is gone; five from one address lock that
+  address out for fifteen minutes; twenty from anywhere close the page for
+  everyone for fifteen minutes.
+- With OAuth on, `/mcp` never answers an unauthenticated request, whether or
+  not a read token is set.
+- Grants live in `<data-dir>/oauth.json` as hashes. Delete the file to sign
+  every agent out at once, running server included; `wazap status` lists who
+  holds one. Disconnecting an agent on its side revokes its refresh token and
+  every access token it minted. A refresh token unused for ninety days is
+  dropped.
+- A read grant never sees a write tool, whatever scope the agent requested.
+  The radio button on the consent page is the only thing that decides.
 
 ## Settings
 
@@ -464,6 +520,8 @@ Claude Code, Claude Desktop, Cursor, Codex, VS Code and any client with an "MCP
 | `WAZAP_TRANSPORT` | `stdio` | `stdio` or `http`. |
 | `WAZAP_HOST` / `WAZAP_PORT` | `127.0.0.1` / `8766` | HTTP bind address. |
 | `WAZAP_READ_TOKEN` / `WAZAP_WRITE_TOKEN` | unset | HTTP bearer tokens. |
+| `WAZAP_PUBLIC_URL` | unset | The `https` address agents reach the server at. With the password, turns OAuth on. |
+| `WAZAP_OAUTH_PASSWORD` | unset | What the consent page asks for. At least 8 characters. |
 | `WAZAP_NO_UPDATE_CHECK` | `0` | `1` stops `status` asking npm for a newer version. |
 | `WAZAP_TRANSCRIBE` | `off` | `local`, `openai` or `off`. |
 | `WAZAP_TRANSCRIBE_AUTO` | `1` | Transcribe incoming voice notes in the background. |

package/dist/cli.js

@@ -19,6 +19,7 @@ import { lockHolder, releaseLock, writeLock } from "./lock.js";
 import { log, logError, say } from "./logger.js";
 import { clockLabel, formatAge } from "./messages.js";
 import { RateLimiter } from "./ratelimit.js";
+import { oauthProblem } from "./oauth.js";
 import { runHttp, runStdio, startLoopbackEndpoint } from "./server.js";
 import { applyWrites } from "./settings.js";
 import { MODELS, downloadModel, maskKey, modelSpec, readTranscribeSettings, stripPasted, transcribeFile, transcribeReady, } from "./transcribe/index.js";
@@ -350,6 +351,13 @@ export async function runServe(config) {
             say(fail(`Refusing to serve ${config.httpHost} without a token. Set WAZAP_READ_TOKEN, or bind 127.0.0.1.`));
             process.exit(1);
         }
+        if (config.transport === "http") {
+            const problem = oauthProblem(config);
+            if (problem) {
+                say(fail(problem));
+                process.exit(1);
+            }
+        }
         mkdirSync(config.dataDir, { recursive: true, mode: 0o700 });
         if (writeLock(p.lockFile)) {
             claimed = true;

package/dist/config.js

@@ -16,6 +16,7 @@ export function paths(dataDir) {
         storeFile: join(dataDir, "store.json"),
         lockFile: join(dataDir, "server.lock"),
         daemonFile: join(dataDir, "daemon.json"),
+        oauthFile: join(dataDir, "oauth.json"),
         envFile: join(dataDir, ".env"),
         qrFile: join(dataDir, "qr.png"),
     };
@@ -140,6 +141,8 @@ export function parseCli(argv = process.argv.slice(2)) {
             httpPort: values.port ? asInt(values.port, 8766) : asInt(process.env.WAZAP_PORT, 8766),
             readToken: (process.env.WAZAP_READ_TOKEN ?? "").trim() || null,
             writeToken: (process.env.WAZAP_WRITE_TOKEN ?? "").trim() || null,
+            publicUrl: (process.env.WAZAP_PUBLIC_URL ?? "").trim().replace(/\/+$/, "") || null,
+            oauthPassword: process.env.WAZAP_OAUTH_PASSWORD || null,
             share: !asBool(process.env.WAZAP_NO_SHARE, false),
             rateLimitPerMinute: asInt(process.env.WAZAP_RATE_LIMIT, 20),
             sources: {

package/dist/doctor.js

@@ -3,6 +3,7 @@ import { readLinkedAccount } from "./auth-state.js";
 import { WAZAP_VERSION, paths } from "./config.js";
 import { asWazapError } from "./errors.js";
 import { lockHolder, lockPid } from "./lock.js";
+import { oauthProblem, readGrants } from "./oauth.js";
 import { MODELS, findWhisper, localProvider, maskKey, modelPath, readTranscribeSettings, which, } from "./transcribe/index.js";
 import { dim, fail, fix, green, info, ok, red } from "./ui.js";
 export const MARK = { ok: "✓", fail: "✗", info: "–" };
@@ -16,6 +17,7 @@ const CHECKS = [
     checkLock,
     checkCredentials,
     checkWrites,
+    checkOAuth,
     checkTranscribe,
     checkUpdate,
 ];
@@ -107,6 +109,23 @@ function checkWrites(config) {
         detail: `${config.readOnly ? "off" : "on"} (${config.sources.readOnly})`,
     };
 }
+/** Only when OAuth is configured: whether it can start, and who is signed in. */
+function checkOAuth(config) {
+    if (!config.publicUrl && !config.oauthPassword)
+        return [];
+    const problem = oauthProblem(config);
+    if (problem)
+        return [{ name: "oauth", state: "fail", detail: problem, fix: "edit <data-dir>/.env" }];
+    if (config.transport !== "http") {
+        return [{ name: "oauth", state: "info", detail: "configured, but only served with WAZAP_TRANSPORT=http" }];
+    }
+    const grants = readGrants(paths(config.dataDir).oauthFile);
+    if (grants.length === 0) {
+        return [{ name: "oauth", state: "info", detail: `on at ${config.publicUrl}, no agent signed in yet` }];
+    }
+    const who = grants.map((g) => `${g.client} (${g.scopes.join("+")})`).join(", ");
+    return [{ name: "oauth", state: "ok", detail: `on at ${config.publicUrl}; signed in: ${who}` }];
+}
 const TRANSCRIBE_OFF_FIX = "run `wazap config transcribe local` to transcribe voice messages";
 const DOWNLOAD_FIX = "run `wazap transcribe download`";
 const KEY_FIX = "run `wazap config transcribe openai`";

package/dist/index.js

@@ -50,7 +50,8 @@ Options:
   -v, --version       Show the version
 
 Environment: WAZAP_DATA_DIR, WAZAP_READ_ONLY, WAZAP_SYNC_FULL_HISTORY, WAZAP_PERSIST_HISTORY,
-WAZAP_TRANSPORT, WAZAP_HOST, WAZAP_PORT, WAZAP_READ_TOKEN, WAZAP_WRITE_TOKEN, WAZAP_RATE_LIMIT,
+WAZAP_TRANSPORT, WAZAP_HOST, WAZAP_PORT, WAZAP_READ_TOKEN, WAZAP_WRITE_TOKEN, WAZAP_PUBLIC_URL,
+WAZAP_OAUTH_PASSWORD, WAZAP_RATE_LIMIT,
 WAZAP_NO_SHARE, WAZAP_NO_UPDATE_CHECK, WAZAP_TRANSCRIBE, WAZAP_TRANSCRIBE_AUTO,
 WAZAP_TRANSCRIBE_LANGUAGE, WAZAP_TRANSCRIBE_API_KEY, WAZAP_TRANSCRIBE_URL, WAZAP_TRANSCRIBE_MODEL,
 WAZAP_WHISPER_MODEL, WAZAP_WHISPER_BIN.

package/dist/oauth.js

@@ -0,0 +1,498 @@
+/**
+ * OAuth 2.1 for hosted agents. claude.ai, ChatGPT and Poke's OAuth mode will
+ * not take a static bearer token; they discover an authorization server, register
+ * themselves (RFC 7591), send the person to a login page and trade a code for
+ * tokens. The SDK's router does discovery, registration, PKCE and the token
+ * endpoint. This file is the part it cannot know: a login page guarded by one
+ * password, which scope the person granted, and where the tokens live.
+ *
+ * There is one user. The password in WAZAP_OAUTH_PASSWORD is the whole identity
+ * layer, so every grant is a deliberate act on the consent page, and the page
+ * asks read or write the way `wazap login` does.
+ */
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { InvalidGrantError, InvalidScopeError, InvalidTokenError } from "@modelcontextprotocol/sdk/server/auth/errors.js";
+import { WAZAP_VERSION } from "./config.js";
+import { log } from "./logger.js";
+export const OAUTH_SCOPES = ["read", "write"];
+/** The consent form posts here; mounted by server.ts next to the SDK router. */
+export const APPROVE_PATH = "/oauth/approve";
+const ACCESS_TOKEN_TTL_MS = 24 * 60 * 60 * 1000;
+const CODE_TTL_MS = 10 * 60 * 1000;
+const PENDING_TTL_MS = 10 * 60 * 1000;
+/** A refresh token nobody has used in this long is a forgotten one. */
+const REFRESH_IDLE_MS = 90 * 24 * 60 * 60 * 1000;
+/** A client that registered and never finished consent. */
+const CLIENT_ORPHAN_MS = 60 * 60 * 1000;
+const LOCKOUT_AFTER = 5;
+const LOCKOUT_MS = 15 * 60 * 1000;
+/** Wrong passwords from everywhere, together, before the page closes for a while. */
+const GLOBAL_LOCKOUT_AFTER = 20;
+/** Wrong passwords one consent page takes before it is thrown away. */
+const PENDING_MISSES = 3;
+const LOOPBACK_HOSTS = ["127.0.0.1", "[::1]", "localhost"];
+/**
+ * OAuth needs both halves and an issuer the SDK and a browser will accept:
+ * https (or loopback, for tests), no path, since every endpoint is mounted at
+ * the root of whatever host this is.
+ */
+export function oauthProblem(config) {
+    if (!config.publicUrl && !config.oauthPassword)
+        return null;
+    if (!config.publicUrl)
+        return "WAZAP_OAUTH_PASSWORD is set but WAZAP_PUBLIC_URL is not. Set both, or neither.";
+    if (!config.oauthPassword)
+        return "WAZAP_PUBLIC_URL is set but WAZAP_OAUTH_PASSWORD is not. Set both, or neither.";
+    let url;
+    try {
+        url = new URL(config.publicUrl);
+    }
+    catch {
+        return `WAZAP_PUBLIC_URL is not a URL: ${config.publicUrl}`;
+    }
+    if (url.search || url.hash)
+        return "WAZAP_PUBLIC_URL must not carry a query or a fragment.";
+    if (url.pathname !== "/") {
+        return "WAZAP_PUBLIC_URL must be a bare origin: the OAuth endpoints live at its root, not under a path.";
+    }
+    if (url.protocol !== "https:" && !LOOPBACK_HOSTS.includes(url.hostname)) {
+        return "WAZAP_PUBLIC_URL must be https, since agents will send a password to it.";
+    }
+    if (config.oauthPassword.length < 8)
+        return "WAZAP_OAUTH_PASSWORD is shorter than 8 characters.";
+    return null;
+}
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function sameSecret(a, b) {
+    const x = Buffer.from(sha256(a));
+    const y = Buffer.from(sha256(b));
+    return timingSafeEqual(x, y);
+}
+function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c] ?? c);
+}
+/** Keep the scopes we know; a client asking for nothing gets read. */
+function normalizeScopes(requested) {
+    const known = (requested ?? []).filter((s) => OAUTH_SCOPES.includes(s));
+    return known.length > 0 ? Array.from(new Set(known)) : ["read"];
+}
+function emptyState() {
+    return { clients: {}, access: {}, refresh: {} };
+}
+function loadState(file) {
+    if (!existsSync(file))
+        return emptyState();
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        return {
+            clients: parsed.clients ?? {},
+            access: parsed.access ?? {},
+            refresh: parsed.refresh ?? {},
+        };
+    }
+    catch (err) {
+        log(`oauth.json unreadable (${err instanceof Error ? err.message : String(err)}), starting with no grants`);
+        return emptyState();
+    }
+}
+function saveState(file, state) {
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    // The mode argument only applies on creation; the chmod covers a leftover temp file.
+    const tmp = `${file}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(state, null, 2), { mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, file);
+}
+/**
+ * Failed passwords, per caller and in total. Five misses lock that caller out
+ * for fifteen minutes; twenty misses from anywhere lock the page for everyone,
+ * so rotating addresses buys an attacker nothing. A consent page itself takes
+ * three wrong passwords and is then gone, which makes every further guess cost
+ * a fresh /authorize, an endpoint the SDK rate-limits.
+ */
+class Lockout {
+    now;
+    misses = new Map();
+    global = { count: 0, at: 0, until: 0 };
+    constructor(now) {
+        this.now = now;
+    }
+    locked(key) {
+        const now = this.now();
+        if (this.global.until > now)
+            return true;
+        const entry = this.misses.get(key);
+        return entry !== undefined && entry.until > now;
+    }
+    miss(key) {
+        const now = this.now();
+        const entry = this.misses.get(key) ?? { count: 0, at: now, until: 0 };
+        entry.count += 1;
+        entry.at = now;
+        if (entry.count >= LOCKOUT_AFTER) {
+            entry.until = now + LOCKOUT_MS;
+            entry.count = 0;
+        }
+        this.misses.set(key, entry);
+        if (now - this.global.at > LOCKOUT_MS)
+            this.global = { count: 0, at: now, until: 0 };
+        this.global.count += 1;
+        if (this.global.count >= GLOBAL_LOCKOUT_AFTER) {
+            this.global = { count: 0, at: now, until: now + LOCKOUT_MS };
+            log("oauth: too many wrong passwords from everywhere, consent closed for fifteen minutes");
+        }
+    }
+    clear(key) {
+        this.misses.delete(key);
+    }
+    /** Forget callers whose misses are older than the window. */
+    prune() {
+        const now = this.now();
+        for (const [key, entry] of this.misses) {
+            if (entry.until <= now && now - entry.at > LOCKOUT_MS)
+                this.misses.delete(key);
+        }
+    }
+}
+function grantsOf(state) {
+    return Object.values(state.refresh).map((entry) => ({
+        client: state.clients[entry.clientId]?.client_name ?? entry.clientId,
+        scopes: entry.scopes,
+        issuedAt: entry.issuedAt,
+    }));
+}
+/** The grants on disk, read by a process that is not the server. */
+export function readGrants(stateFile) {
+    return grantsOf(loadState(stateFile));
+}
+export class WazapOAuthProvider {
+    options;
+    state;
+    pending = new Map();
+    codes = new Map();
+    lockout;
+    now;
+    clientsStore;
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? Date.now;
+        this.state = loadState(options.stateFile);
+        this.lockout = new Lockout(this.now);
+        this.clientsStore = {
+            getClient: (clientId) => this.state.clients[clientId],
+            registerClient: (client) => {
+                const full = {
+                    ...client,
+                    client_id: randomBytes(16).toString("hex"),
+                    client_id_issued_at: Math.floor(this.now() / 1000),
+                };
+                this.state.clients[full.client_id] = full;
+                this.persist();
+                log(`oauth: registered client "${full.client_name ?? full.client_id}"`);
+                return full;
+            },
+        };
+    }
+    /** The authorization server and the protected resource are one process. */
+    get issuerUrl() {
+        return this.options.publicUrl;
+    }
+    get resourceUrl() {
+        return new URL("/mcp", this.options.publicUrl);
+    }
+    persist() {
+        saveState(this.options.stateFile, this.state);
+    }
+    /** Deleting oauth.json is the documented way to sign everyone out; honour it while running. */
+    sync() {
+        const populated = Object.keys(this.state.clients).length + Object.keys(this.state.access).length + Object.keys(this.state.refresh).length > 0;
+        if (populated && !existsSync(this.options.stateFile)) {
+            log("oauth: oauth.json is gone, every grant is revoked");
+            this.state.clients = {};
+            this.state.access = {};
+            this.state.refresh = {};
+            this.codes.clear();
+        }
+    }
+    sweep() {
+        this.sync();
+        this.lockout.prune();
+        const now = this.now();
+        for (const [id, entry] of this.pending)
+            if (now - entry.createdAt > PENDING_TTL_MS)
+                this.pending.delete(id);
+        for (const [code, entry] of this.codes)
+            if (now - entry.createdAt > CODE_TTL_MS)
+                this.codes.delete(code);
+        let dirty = false;
+        for (const [hash, entry] of Object.entries(this.state.access)) {
+            if (entry.expiresAt !== undefined && entry.expiresAt < now) {
+                delete this.state.access[hash];
+                dirty = true;
+            }
+        }
+        for (const [hash, entry] of Object.entries(this.state.refresh)) {
+            if (now - (entry.lastUsedAt ?? entry.issuedAt) > REFRESH_IDLE_MS) {
+                delete this.state.refresh[hash];
+                dirty = true;
+            }
+        }
+        // A client with no grant and nothing in flight is a registration nobody finished.
+        const holding = new Set();
+        for (const entry of Object.values(this.state.refresh))
+            holding.add(entry.clientId);
+        for (const entry of Object.values(this.state.access))
+            holding.add(entry.clientId);
+        for (const entry of this.pending.values())
+            holding.add(entry.client.client_id);
+        for (const entry of this.codes.values())
+            holding.add(entry.clientId);
+        for (const [id, client] of Object.entries(this.state.clients)) {
+            const issuedAt = (client.client_id_issued_at ?? 0) * 1000;
+            if (!holding.has(id) && now - issuedAt > CLIENT_ORPHAN_MS) {
+                delete this.state.clients[id];
+                dirty = true;
+            }
+        }
+        if (dirty)
+            this.persist();
+    }
+    // --- authorization -------------------------------------------------------
+    /** The SDK has validated client and redirect_uri; park the request and show the page. */
+    async authorize(client, params, res) {
+        this.sweep();
+        const id = randomBytes(24).toString("hex");
+        this.pending.set(id, { client, params, createdAt: this.now(), misses: 0 });
+        res.setHeader("Cache-Control", "no-store");
+        res.status(200).type("html").send(this.consentPage(id, client, params));
+    }
+    /** Express handler for the consent form. Mount with urlencoded parsing. */
+    approve = (req, res) => {
+        this.sweep();
+        const body = (req.body ?? {});
+        const id = typeof body.request === "string" ? body.request : "";
+        const entry = this.pending.get(id);
+        if (!entry) {
+            res.status(400).type("html").send(this.messagePage("This sign-in link has expired. Go back to the agent and connect again."));
+            return;
+        }
+        const { client, params } = entry;
+        const fail = (error, description) => {
+            this.pending.delete(id);
+            const url = new URL(params.redirectUri);
+            url.searchParams.set("error", error);
+            url.searchParams.set("error_description", description);
+            if (params.state)
+                url.searchParams.set("state", params.state);
+            res.redirect(url.href);
+        };
+        if (body.decision !== "allow") {
+            fail("access_denied", "The user declined.");
+            return;
+        }
+        const caller = req.ip ?? "unknown";
+        if (this.lockout.locked(caller)) {
+            res.status(429).type("html").send(this.messagePage("Too many wrong passwords. Try again in fifteen minutes."));
+            return;
+        }
+        const password = typeof body.password === "string" ? body.password : "";
+        if (!sameSecret(password, this.options.password)) {
+            this.lockout.miss(caller);
+            entry.misses += 1;
+            log(`oauth: wrong password from ${caller}`);
+            if (entry.misses >= PENDING_MISSES) {
+                this.pending.delete(id);
+                res.status(401).type("html").send(this.messagePage("Wrong password, three times. Go back to the agent and connect again."));
+                return;
+            }
+            res.status(401).type("html").send(this.consentPage(id, client, params, "Wrong password."));
+            return;
+        }
+        this.lockout.clear(caller);
+        this.pending.delete(id);
+        const scopes = body.access === "write" ? ["read", "write"] : ["read"];
+        const code = randomBytes(32).toString("hex");
+        this.codes.set(code, {
+            clientId: client.client_id,
+            codeChallenge: params.codeChallenge,
+            redirectUri: params.redirectUri,
+            scopes,
+            createdAt: this.now(),
+        });
+        log(`oauth: granted ${scopes.join("+")} to "${client.client_name ?? client.client_id}"`);
+        const url = new URL(params.redirectUri);
+        url.searchParams.set("code", code);
+        if (params.state)
+            url.searchParams.set("state", params.state);
+        res.redirect(url.href);
+    };
+    async challengeForAuthorizationCode(client, code) {
+        const entry = this.codes.get(code);
+        if (!entry || entry.clientId !== client.client_id)
+            throw new InvalidGrantError("Unknown authorization code");
+        return entry.codeChallenge;
+    }
+    async exchangeAuthorizationCode(client, code, _codeVerifier, redirectUri) {
+        this.sweep();
+        const entry = this.codes.get(code);
+        if (!entry || entry.clientId !== client.client_id)
+            throw new InvalidGrantError("Unknown authorization code");
+        if (redirectUri !== undefined && redirectUri !== entry.redirectUri)
+            throw new InvalidGrantError("redirect_uri mismatch");
+        // One use: a replayed code must fail even inside its ten minutes.
+        this.codes.delete(code);
+        return this.issue(client.client_id, entry.scopes);
+    }
+    async exchangeRefreshToken(client, refreshToken, scopes) {
+        this.sweep();
+        const entry = this.state.refresh[sha256(refreshToken)];
+        if (!entry || entry.clientId !== client.client_id)
+            throw new InvalidGrantError("Unknown refresh token");
+        // A refresh may narrow the grant, never widen it.
+        const granted = scopes && scopes.length > 0 ? scopes.filter((s) => entry.scopes.includes(s)) : entry.scopes;
+        if (granted.length === 0)
+            throw new InvalidScopeError("Requested scopes exceed the grant");
+        return this.issue(client.client_id, granted, refreshToken);
+    }
+    issue(clientId, scopes, existingRefresh) {
+        const now = this.now();
+        let refreshToken = existingRefresh;
+        if (!refreshToken) {
+            refreshToken = randomBytes(32).toString("hex");
+            this.state.refresh[sha256(refreshToken)] = { clientId, scopes, issuedAt: now, lastUsedAt: now };
+        }
+        else {
+            const refresh = this.state.refresh[sha256(refreshToken)];
+            if (refresh)
+                refresh.lastUsedAt = now;
+        }
+        const accessToken = randomBytes(32).toString("hex");
+        this.state.access[sha256(accessToken)] = {
+            clientId,
+            scopes,
+            issuedAt: now,
+            expiresAt: now + ACCESS_TOKEN_TTL_MS,
+            refresh: sha256(refreshToken),
+        };
+        this.persist();
+        return {
+            access_token: accessToken,
+            token_type: "bearer",
+            expires_in: Math.floor(ACCESS_TOKEN_TTL_MS / 1000),
+            refresh_token: refreshToken,
+            scope: scopes.join(" "),
+        };
+    }
+    async verifyAccessToken(token) {
+        this.sync();
+        const entry = this.state.access[sha256(token)];
+        if (!entry)
+            throw new InvalidTokenError("Unknown access token");
+        if (entry.expiresAt !== undefined && entry.expiresAt < this.now())
+            throw new InvalidTokenError("Access token expired");
+        return {
+            token,
+            clientId: entry.clientId,
+            scopes: entry.scopes,
+            expiresAt: entry.expiresAt === undefined ? undefined : Math.floor(entry.expiresAt / 1000),
+            resource: this.resourceUrl,
+        };
+    }
+    /**
+     * Look the token up as either kind; the caller may not say which. Revoking a
+     * refresh token also ends every access token it minted, so "disconnect" in
+     * an agent's settings means disconnected now, not in up to a day.
+     */
+    async revokeToken(client, request) {
+        this.sync();
+        const hash = sha256(request.token);
+        let dirty = false;
+        const access = this.state.access[hash];
+        if (access && access.clientId === client.client_id) {
+            delete this.state.access[hash];
+            dirty = true;
+        }
+        const refresh = this.state.refresh[hash];
+        if (refresh && refresh.clientId === client.client_id) {
+            delete this.state.refresh[hash];
+            for (const [accessHash, entry] of Object.entries(this.state.access)) {
+                if (entry.refresh === hash)
+                    delete this.state.access[accessHash];
+            }
+            dirty = true;
+        }
+        if (dirty)
+            this.persist();
+    }
+    /** Every grant, for `wazap status` and the like. */
+    grants() {
+        this.sync();
+        return grantsOf(this.state);
+    }
+    // --- pages ---------------------------------------------------------------
+    consentPage(id, client, params, error) {
+        const rawName = client.client_name ?? new URL(params.redirectUri).hostname;
+        const name = escapeHtml(rawName);
+        const wantsWrite = normalizeScopes(params.scopes).includes("write");
+        return page(`Connect ${rawName}`, `
+<h1>Connect <strong>${name}</strong> to WhatsApp?</h1>
+<p>This agent wants to use the WhatsApp account behind this wazap.</p>
+${error ? `<p class="error">${escapeHtml(error)}</p>` : ""}
+<form method="post" action="${APPROVE_PATH}">
+  <input type="hidden" name="request" value="${id}">
+  <fieldset>
+    <legend>What may it do?</legend>
+    <label><input type="radio" name="access" value="read"${wantsWrite ? "" : " checked"}> Read chats and contacts</label>
+    <label><input type="radio" name="access" value="write"${wantsWrite ? " checked" : ""}> Read, and send messages as you</label>
+  </fieldset>
+  <label class="field">wazap password
+    <input type="password" name="password" autocomplete="current-password" autofocus required>
+  </label>
+  <div class="actions">
+    <button type="submit" name="decision" value="allow">Connect</button>
+    <button type="submit" name="decision" value="deny" class="secondary" formnovalidate>Cancel</button>
+  </div>
+</form>`);
+    }
+    messagePage(text) {
+        return page("wazap", `<h1>wazap</h1><p>${escapeHtml(text)}</p>`);
+    }
+}
+function page(title, body) {
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex">
+<title>${escapeHtml(title)} · wazap</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { margin: 0; min-height: 100vh; display: grid; place-items: center; font: 16px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif; background: Canvas; color: CanvasText; }
+  main { width: min(28rem, calc(100vw - 2rem)); padding: 2rem; border: 1px solid color-mix(in srgb, CanvasText 15%, transparent); border-radius: 12px; }
+  h1 { font-size: 1.25rem; margin: 0 0 .5rem; }
+  p { margin: 0 0 1rem; }
+  fieldset { border: 0; padding: 0; margin: 0 0 1rem; }
+  legend { font-weight: 600; margin-bottom: .25rem; }
+  label { display: block; margin: .25rem 0; }
+  .field { font-weight: 600; margin-bottom: 1rem; }
+  .field input { display: block; width: 100%; box-sizing: border-box; margin-top: .25rem; padding: .5rem .6rem; font: inherit; border: 1px solid color-mix(in srgb, CanvasText 30%, transparent); border-radius: 8px; background: Field; color: FieldText; }
+  .actions { display: flex; gap: .5rem; }
+  button { font: inherit; padding: .55rem 1rem; border-radius: 8px; border: 1px solid #25d366; background: #25d366; color: #062b14; cursor: pointer; }
+  button.secondary { background: transparent; border-color: color-mix(in srgb, CanvasText 30%, transparent); color: inherit; }
+  .error { color: #c62828; font-weight: 600; }
+  footer { margin-top: 1.5rem; font-size: .8rem; opacity: .6; }
+</style>
+</head>
+<body>
+<main>
+${body}
+<footer>wazap ${escapeHtml(WAZAP_VERSION)}</footer>
+</main>
+</body>
+</html>`;
+}

package/dist/server.js

@@ -1,10 +1,13 @@
 import { randomUUID, timingSafeEqual } from "node:crypto";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { mcpAuthRouter, getOAuthProtectedResourceMetadataUrl } from "@modelcontextprotocol/sdk/server/auth/router.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import express from "express";
-import { WAZAP_VERSION } from "./config.js";
+import { rateLimit } from "express-rate-limit";
+import { WAZAP_VERSION, paths } from "./config.js";
+import { APPROVE_PATH, OAUTH_SCOPES, WazapOAuthProvider } from "./oauth.js";
 import { registerTools } from "./tools.js";
 import { log, logError } from "./logger.js";
 function isAuthorized(header, expected) {
@@ -35,29 +38,72 @@ export async function startHttpEndpoint(wa, config, endpoint, limiter) {
         const rpc = (req.body && typeof req.body === "object" ? req.body.method : undefined) ?? "-";
         const hasAuth = req.headers.authorization ? "auth" : "noauth";
         res.on("finish", () => {
-            log(`HTTP ${req.method} ${req.url} rpc=${rpc} ${hasAuth} accept="${req.headers.accept ?? ""}" -> ${res.statusCode} (${Date.now() - start}ms)`);
+            log(`HTTP ${req.method} ${req.originalUrl} rpc=${rpc} ${hasAuth} accept="${req.headers.accept ?? ""}" -> ${res.statusCode} (${Date.now() - start}ms)`);
         });
         res.on("close", () => {
             if (!res.writableEnded) {
-                log(`HTTP ${req.method} ${req.url} rpc=${rpc} -> client closed before response (${Date.now() - start}ms)`);
+                log(`HTTP ${req.method} ${req.originalUrl} rpc=${rpc} -> client closed before response (${Date.now() - start}ms)`);
             }
         });
         next();
     });
-    if (endpoint.openRead) {
+    if (endpoint.openRead && !endpoint.oauth) {
         log("WARNING: no WAZAP_READ_TOKEN set, the /mcp endpoint is UNAUTHENTICATED. " +
             "Set WAZAP_READ_TOKEN before exposing this server beyond localhost.");
     }
+    const oauth = endpoint.oauth;
+    // A server that advertises sign-in must not also answer strangers.
+    const openRead = endpoint.openRead && !oauth;
+    if (oauth) {
+        // Reached through a TLS proxy: on this machine, or the Docker bridge when
+        // the container binds 0.0.0.0. The proxy's idea of the caller is the one
+        // the password lockout and the SDK's limiters should count.
+        app.set("trust proxy", "loopback, linklocal, uniquelocal");
+        app.use(mcpAuthRouter({
+            provider: oauth,
+            issuerUrl: oauth.issuerUrl,
+            resourceServerUrl: oauth.resourceUrl,
+            resourceName: "wazap",
+            scopesSupported: [...OAUTH_SCOPES],
+            serviceDocumentationUrl: new URL("https://github.com/razvangirgiz/wazap#self-host"),
+            // A confidential client's secret would otherwise expire after thirty
+            // days and its refresh token with it, which is a monthly password.
+            clientRegistrationOptions: { clientSecretExpirySeconds: 0 },
+        }));
+        app.post(APPROVE_PATH, rateLimit({ windowMs: 15 * 60 * 1000, limit: 30, standardHeaders: true, legacyHeaders: false }), express.urlencoded({ extended: false }), oauth.approve);
+        log(`OAuth on: agents sign in at ${oauth.issuerUrl.href}`);
+    }
+    const resourceMetadataUrl = oauth ? getOAuthProtectedResourceMetadataUrl(oauth.resourceUrl) : null;
     // The first credential the bearer token matches decides the session's tools,
-    // so a leaked read token can never message anyone.
-    const requireAuth = (req, res, next) => {
+    // so a leaked read token can never message anyone. An OAuth token carries
+    // the scope the person picked on the consent page.
+    const requireAuth = async (req, res, next) => {
         const auth = req.headers.authorization;
         const credential = endpoint.credentials.find((entry) => isAuthorized(auth, entry.token));
-        if (credential || endpoint.openRead) {
-            req.mcpWrite = credential?.write === true;
+        if (credential) {
+            req.mcpWrite = credential.write;
             next();
             return;
         }
+        if (oauth && auth?.startsWith("Bearer ")) {
+            try {
+                const info = await oauth.verifyAccessToken(auth.slice("Bearer ".length).trim());
+                req.mcpWrite = info.scopes.includes("write");
+                next();
+                return;
+            }
+            catch {
+                // Falls through to the 401 below, which tells the client how to sign in.
+            }
+        }
+        if (openRead) {
+            req.mcpWrite = false;
+            next();
+            return;
+        }
+        if (resourceMetadataUrl) {
+            res.setHeader("WWW-Authenticate", `Bearer resource_metadata="${resourceMetadataUrl}"`);
+        }
         res.status(401).json({
             jsonrpc: "2.0",
             error: { code: -32001, message: "Unauthorized: missing or invalid bearer token" },
@@ -110,9 +156,12 @@ export async function startHttpEndpoint(wa, config, endpoint, limiter) {
             }
         }
     };
-    app.post("/mcp", requireAuth, handleMcp);
-    app.get("/mcp", requireAuth, handleMcp);
-    app.delete("/mcp", requireAuth, handleMcp);
+    const authed = (req, res, next) => {
+        requireAuth(req, res, next).catch(next);
+    };
+    app.post("/mcp", authed, handleMcp);
+    app.get("/mcp", authed, handleMcp);
+    app.delete("/mcp", authed, handleMcp);
     // Unauthenticated, so it carries liveness only; the account and data dir
     // stay behind the token in get_status.
     app.get("/healthz", (_req, res) => {
@@ -123,6 +172,12 @@ export async function startHttpEndpoint(wa, config, endpoint, limiter) {
             const bound = server.address();
             resolve(typeof bound === "object" && bound !== null ? bound.port : endpoint.port);
         });
+        endpoint.signal?.addEventListener("abort", () => {
+            for (const transport of transports.values())
+                void transport.close();
+            server.closeAllConnections();
+            server.close();
+        });
     });
 }
 /** The endpoint the user asked for: WAZAP_HOST/WAZAP_PORT and the two configured tokens. */
@@ -134,7 +189,14 @@ export async function runHttp(wa, config, limiter, extra) {
         credentials.push({ token: config.writeToken, write: true });
     if (extra)
         credentials.push(extra);
-    const port = await startHttpEndpoint(wa, config, { host: config.httpHost, port: config.httpPort, credentials, openRead: !config.readToken }, limiter);
+    const oauth = config.publicUrl && config.oauthPassword
+        ? new WazapOAuthProvider({
+            publicUrl: new URL(config.publicUrl),
+            password: config.oauthPassword,
+            stateFile: paths(config.dataDir).oauthFile,
+        })
+        : undefined;
+    const port = await startHttpEndpoint(wa, config, { host: config.httpHost, port: config.httpPort, credentials, openRead: !config.readToken, oauth }, limiter);
     log(`MCP server (Streamable HTTP) on http://${config.httpHost}:${port}/mcp`);
     return port;
 }

package/dist/settings.js

@@ -41,7 +41,9 @@ const SETTINGS = [
     {
         label: "transport",
         source: "transport",
-        value: (config) => (config.transport === "http" ? `http ${config.httpHost}:${config.httpPort}` : "stdio"),
+        value: (config) => config.transport === "http"
+            ? `http ${config.httpHost}:${config.httpPort}${config.publicUrl && config.oauthPassword ? ` · oauth at ${config.publicUrl}` : ""}`
+            : "stdio",
     },
     {
         label: "rate limit",

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "wazap-mcp",
-  "version": "0.9.8",
+  "version": "0.10.0",
   "mcpName": "io.github.razvangirgiz/wazap",
-  "description": "WhatsApp for your AI agent. MCP server over Baileys: pairing-code login, 24 tools, stdio or token-protected HTTP.",
+  "description": "WhatsApp for your AI agent. MCP server over Baileys: pairing-code login, 24 tools, stdio or HTTP with bearer tokens and OAuth.",
   "license": "MIT",
   "author": "Răzvan Girgiz",
   "repository": {
@@ -52,6 +52,7 @@
     "baileys": "7.0.0-rc14",
     "dotenv": "^16.4.5",
     "express": "^4.22.2",
+    "express-rate-limit": "^8.2.1",
     "qrcode": "^1.5.4",
     "qrcode-terminal": "^0.12.0",
     "zod": "^3.24.1"