@alfe.ai/social-mcp 0.2.3 → 0.2.5

package/README.md

@@ -16,6 +16,25 @@ npm install @alfe.ai/social-mcp
 npx @alfe.ai/social-mcp --provider bluesky
 ```
 
+The server starts even when the agent has no connected Bluesky account, so
+`social_list_accounts` can explain the empty state. Every other tool requires
+an explicit `account` selector returned by that discovery call.
+
+## Runtime boundaries
+
+- Provider selection accepts exactly `--provider bluesky`,
+  `--provider=bluesky`, or the positional `bluesky` form.
+- Bluesky PDS endpoints must be clean HTTPS origins. The driver rejects IP
+  literals and reserved hostnames, then resolves and rejects private or
+  reserved addresses immediately before each request. XRPC redirects are
+  rejected so bearer requests cannot escape the validated origin.
+- Provider bodies and model-facing tool results have byte ceilings. Provider
+  exception bodies are never returned to the model.
+- Delete accepts only an exact `app.bsky.feed.post` AT URI owned by the
+  selected account; a foreign-author URI is rejected before the PDS call.
+- Importing the package is inert. Signal handlers are installed only while the
+  executable is running and close the MCP server before the process exits.
+
 ## Links
 
 - 🌐 Website: <https://alfe.ai>

package/dist/server.js

@@ -1,9 +1,14 @@
 #!/usr/bin/env node
+import { createRequire } from "node:module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { resolveConfig } from "@alfe.ai/config";
 import { AgentApiClient } from "@alfe.ai/agent-api-client";
 import { assertPatternA } from "@alfe.ai/mcp-bundler";
+import dns from "node:dns/promises";
+import { BlockList, isIP } from "node:net";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
 import { z } from "zod";
 //#region src/args.ts
 /**
@@ -39,33 +44,37 @@ function isSupportedProvider(value) {
 * misconfiguration, distinct from the zero-account (graceful) path.
 */
 function parseProviderArg(argv) {
+	if (argv.length === 0) return missingProvider();
+	if (argv.length > 2) return {
+		ok: false,
+		error: "Invalid social provider arguments. Pass exactly --provider <id>, --provider=<id>, or <id>."
+	};
 	let raw;
-	for (let i = 0; i < argv.length; i++) {
-		const arg = argv[i];
-		if (arg === "--provider") {
-			raw = argv[i + 1];
-			break;
-		}
-		if (arg.startsWith("--provider=")) {
-			raw = arg.slice(11);
-			break;
-		}
-		if (raw === void 0 && !arg.startsWith("-")) raw = arg;
-	}
-	if (!raw) return {
+	const first = argv[0];
+	if (first === "--provider" && argv.length === 2) raw = argv[1];
+	else if (first.startsWith("--provider=") && argv.length === 1) raw = first.slice(11);
+	else if (!first.startsWith("-") && argv.length === 1) raw = first;
+	else return {
 		ok: false,
-		error: `No social provider selected. Pass one via --provider (e.g. "--provider bluesky"). Supported: ${SUPPORTED_PROVIDERS.join(", ")}.`
+		error: "Invalid social provider arguments. Pass exactly --provider <id>, --provider=<id>, or <id>."
 	};
+	if (!raw || raw.length > 64) return missingProvider();
 	const provider = raw.trim().toLowerCase();
 	if (!isSupportedProvider(provider)) return {
 		ok: false,
-		error: `Unsupported social provider "${raw}". Supported: ${SUPPORTED_PROVIDERS.join(", ")}.`
+		error: `Unsupported social provider. Supported: ${SUPPORTED_PROVIDERS.join(", ")}.`
 	};
 	return {
 		ok: true,
 		provider
 	};
 }
+function missingProvider() {
+	return {
+		ok: false,
+		error: `No social provider selected. Pass one via --provider (e.g. "--provider bluesky"). Supported: ${SUPPORTED_PROVIDERS.join(", ")}.`
+	};
+}
 //#endregion
 //#region src/drivers/facets.ts
 /**
@@ -76,7 +85,8 @@ function parseProviderArg(argv) {
 */
 const URL_RE = /https?:\/\/[^\s]+/g;
 /** Trailing chars to strip from a matched URL (sentence punctuation, closers). */
-const TRAILING_TRIM = /[.,;:!?)\]}'"]+$/;
+const TRAILING_PUNCTUATION = /[.,;:!?'"]+$/u;
+const MAX_LINK_LENGTH = 2048;
 const encoder = new TextEncoder();
 /** UTF-8 byte length of a string — the unit Bluesky facet offsets are in. */
 function utf8Len(text) {
@@ -96,9 +106,8 @@ function detectLinkFacets(text) {
 	for (const match of text.matchAll(URL_RE)) {
 		const start = match.index;
 		let raw = match[0];
-		const trimmed = raw.replace(TRAILING_TRIM, "");
-		if (!trimmed) continue;
-		raw = trimmed;
+		raw = trimTrailingPunctuation(raw);
+		if (!isSafeHttpUrl(raw)) continue;
 		const end = start + raw.length;
 		const byteStart = utf8Len(text.slice(0, start));
 		const byteEnd = byteStart + utf8Len(text.slice(start, end));
@@ -115,13 +124,175 @@ function detectLinkFacets(text) {
 	}
 	return facets;
 }
+function trimTrailingPunctuation(value) {
+	let candidate = value.replace(TRAILING_PUNCTUATION, "");
+	for (const [open, close] of [
+		["(", ")"],
+		["[", "]"],
+		["{", "}"]
+	]) while (candidate.endsWith(close) && count(candidate, close) > count(candidate, open)) candidate = candidate.slice(0, -1);
+	return candidate;
+}
+function count(value, needle) {
+	let total = 0;
+	let offset = 0;
+	while ((offset = value.indexOf(needle, offset)) !== -1) {
+		total += 1;
+		offset += needle.length;
+	}
+	return total;
+}
+function isSafeHttpUrl(value) {
+	if (value.length === 0 || value.length > MAX_LINK_LENGTH) return false;
+	try {
+		const url = new URL(value);
+		return (url.protocol === "https:" || url.protocol === "http:") && url.hostname.length > 0 && url.username.length === 0 && url.password.length === 0;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/boundary.ts
+const MAX_PROVIDER_RESPONSE_BYTES = 2 * 1024 * 1024;
+const MAX_TOOL_RESPONSE_BYTES = 512 * 1024;
+function isRecord(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+/** Read one provider response without allowing an untrusted PDS to exhaust memory. */
+async function readProviderJson(response) {
+	const declared = response.headers.get("content-length");
+	if (declared !== null && (!/^\d+$/u.test(declared) || Number(declared) > MAX_PROVIDER_RESPONSE_BYTES)) {
+		await response.body?.cancel().catch(() => void 0);
+		throw new Error("social_provider_response_too_large");
+	}
+	if (response.body === null) throw new Error("social_provider_response_empty");
+	const reader = response.body.getReader();
+	const decoder = new TextDecoder();
+	let bytes = 0;
+	let text = "";
+	try {
+		for (;;) {
+			const chunk = await reader.read();
+			if (chunk.done) break;
+			if (chunk.value === void 0) throw new Error("social_provider_response_invalid");
+			bytes += chunk.value.byteLength;
+			if (bytes > MAX_PROVIDER_RESPONSE_BYTES) {
+				await reader.cancel("response too large").catch(() => void 0);
+				throw new Error("social_provider_response_too_large");
+			}
+			text += decoder.decode(chunk.value, { stream: true });
+		}
+		text += decoder.decode();
+	} finally {
+		reader.releaseLock();
+	}
+	try {
+		return JSON.parse(text);
+	} catch {
+		throw new Error("social_provider_response_invalid");
+	}
+}
+/** Serialize a model-facing result with a hard byte ceiling and no raw exception text. */
+function toolResult(data) {
+	try {
+		const serialized = JSON.stringify(data, null, 2);
+		if (typeof serialized !== "string" || Buffer.byteLength(serialized, "utf8") > MAX_TOOL_RESPONSE_BYTES) throw new Error("result too large");
+		return { content: [{
+			type: "text",
+			text: serialized
+		}] };
+	} catch {
+		return toolError();
+	}
+}
+/** Keep provider bodies, selectors, routing hosts, and credential details out of tool errors. */
+function toolError() {
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify({
+				error: "social_request_failed",
+				message: "The social request could not be completed. Check the account connection and try again."
+			})
+		}],
+		isError: true
+	};
+}
+function boundedString(value, maxLength) {
+	return typeof value === "string" && value.length > 0 && value.length <= maxLength ? value : void 0;
+}
+function boundedOptionalString(value, maxLength) {
+	return typeof value === "string" && value.length <= maxLength ? value : void 0;
+}
+function nonNegativeCount(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : 0;
+}
 //#endregion
 //#region src/drivers/bluesky.ts
+/**
+* Bluesky `SocialDriver` — AT-protocol XRPC against the account's own PDS.
+*
+* Credentials come from `AgentApiClient.getSocialAccounts("bluesky")`. Each
+* account entry's `accessToken` is the RAW JSON session bundle string
+* (`{ accessJwt, refreshJwt, did }`) that `services/connect`'s Bluesky
+* provider wrote; `providerMetadata` carries the non-secret routing fields
+* `{ handle, pdsHost, did }`. We parse the `accessJwt` out of the bundle and
+* Bearer it on every XRPC call; `pdsHost` (default `https://bsky.social`)
+* targets the account's PDS.
+*
+* Token refresh is DELEGATED TO CONNECT, never done here: on a 401 /
+* ExpiredToken we call `AgentApiClient.refreshSocialAccount("bluesky", did)`
+* (which drives connect's `refreshSession` + rotation persistence) and then
+* re-fetch accounts to pick up the fresh `accessJwt`. We never call
+* `com.atproto.server.refreshSession` ourselves — connect owns the encrypted
+* refreshJwt and its rotation.
+*
+* SSRF defence-in-depth: connect validates `pdsHost` at store time, and this
+* process re-validates the exact origin plus its current DNS answers before
+* every request. This closes stale store-time resolution; callers must still
+* treat DNS validation + fetch as a best-effort boundary because Node fetch
+* does not expose connection-address pinning here.
+*
+* Bluesky posts against the tenant's OWN PDS with the tenant's OWN token, so
+* there is ZERO Alfe-funded cost — this driver is UNMETERED, matching the
+* `@alfe.ai/github-mcp` precedent. See `drivers/types.ts` → metering seam for
+* how a funded platform (X/Reddit) would wire preflight/meter instead.
+*/
 const DEFAULT_PDS_HOST = "https://bsky.social";
-/** Bluesky's hard post-text limit is 300 graphemes; we enforce on JS length as a floor. */
-const POST_TEXT_MAX = 300;
+const POST_GRAPHEME_MAX = 300;
+const POST_UTF8_MAX = 3e3;
 /** Bound every XRPC call so a hung PDS can't stall the MCP server. */
 const XRPC_TIMEOUT_MS = 1e4;
+const DNS_TIMEOUT_MS = 5e3;
+const MAX_ACCOUNTS = 200;
+const MAX_ACCESS_JWT_LENGTH = 32 * 1024;
+const MAX_SESSION_BUNDLE_LENGTH = 96 * 1024;
+const POST_COLLECTION = "app.bsky.feed.post";
+const PRIVATE_ADDRESS_BLOCKLIST = new BlockList();
+for (const [network, prefix] of [
+	["0.0.0.0", 8],
+	["10.0.0.0", 8],
+	["100.64.0.0", 10],
+	["127.0.0.0", 8],
+	["169.254.0.0", 16],
+	["172.16.0.0", 12],
+	["192.0.0.0", 24],
+	["192.0.2.0", 24],
+	["192.168.0.0", 16],
+	["198.18.0.0", 15],
+	["198.51.100.0", 24],
+	["203.0.113.0", 24],
+	["224.0.0.0", 4],
+	["240.0.0.0", 4]
+]) PRIVATE_ADDRESS_BLOCKLIST.addSubnet(network, prefix, "ipv4");
+PRIVATE_ADDRESS_BLOCKLIST.addAddress("::", "ipv6");
+PRIVATE_ADDRESS_BLOCKLIST.addAddress("::1", "ipv6");
+PRIVATE_ADDRESS_BLOCKLIST.addSubnet("fc00::", 7, "ipv6");
+PRIVATE_ADDRESS_BLOCKLIST.addSubnet("fe80::", 10, "ipv6");
+PRIVATE_ADDRESS_BLOCKLIST.addSubnet("ff00::", 8, "ipv6");
+PRIVATE_ADDRESS_BLOCKLIST.addSubnet("2001:db8::", 32, "ipv6");
 const CAPABILITIES = {
 	postText: true,
 	reply: true,
@@ -131,30 +302,64 @@ const CAPABILITIES = {
 	search: true,
 	deletePost: true
 };
-/** Reject any non-https PDS host (defence-in-depth SSRF guard). */
+/** Validate and canonicalise one PDS origin without doing network I/O. */
 function assertHttpsPdsHost(pdsHost) {
 	let url;
 	try {
 		url = new URL(pdsHost);
 	} catch {
-		throw new Error(`Invalid pdsHost "${pdsHost}"`);
+		throw new Error("Invalid pdsHost");
+	}
+	if (url.protocol !== "https:") throw new Error("Refusing non-https pdsHost (SSRF guard)");
+	if (url.username || url.password || url.pathname !== "/" || url.search || url.hash || url.hostname.length === 0) throw new Error("Invalid pdsHost origin");
+	const host = url.hostname.toLowerCase().replace(/^\[|\]$/gu, "").replace(/\.$/u, "");
+	if (host === "localhost" || host === "metadata" || host.endsWith(".local") || host.endsWith(".internal") || isIP(host) !== 0) throw new Error("Refusing reserved pdsHost (SSRF guard)");
+}
+async function assertPublicPdsHost(pdsHost, resolveHost) {
+	assertHttpsPdsHost(pdsHost);
+	const host = new URL(pdsHost).hostname.toLowerCase().replace(/\.$/u, "");
+	let addresses;
+	let timeout;
+	try {
+		addresses = await Promise.race([resolveHost(host), new Promise((_, reject) => {
+			timeout = setTimeout(() => {
+				reject(/* @__PURE__ */ new Error("dns_timeout"));
+			}, DNS_TIMEOUT_MS);
+		})]);
+	} catch {
+		throw new Error("pds_host_dns_failed");
+	} finally {
+		if (timeout !== void 0) clearTimeout(timeout);
+	}
+	if (addresses.length === 0) throw new Error("pds_host_dns_failed");
+	for (const { address } of addresses) {
+		const family = isIP(address);
+		if (family === 0 || PRIVATE_ADDRESS_BLOCKLIST.check(address, family === 4 ? "ipv4" : "ipv6")) throw new Error("pds_host_resolved_to_private_address");
 	}
-	if (url.protocol !== "https:") throw new Error(`Refusing non-https pdsHost "${pdsHost}" (SSRF guard)`);
 }
 /**
 * Parse a `getSocialAccounts` entry into a usable {@link BlueskyAccount} or a
 * {@link DegradedAccount}. Exported for unit testing the bundle-parse contract.
 */
 function parseAccountEntry(entry) {
-	const meta = entry.providerMetadata;
-	const handle = typeof meta.handle === "string" ? meta.handle : "";
-	const did = entry.accountIdentifier || (typeof meta.did === "string" ? meta.did : "");
-	const pdsHost = typeof meta.pdsHost === "string" && meta.pdsHost ? meta.pdsHost : DEFAULT_PDS_HOST;
+	const meta = isRecord(entry.providerMetadata) ? entry.providerMetadata : {};
+	const handle = boundedOptionalString(meta.handle, 256) ?? "";
+	const metadataDid = boundedOptionalString(meta.did, 256) ?? "";
+	const did = boundedString(entry.accountIdentifier, 256) ?? metadataDid;
+	const pdsHost = boundedString(meta.pdsHost, 2048) ?? DEFAULT_PDS_HOST;
 	const base = {
 		did,
 		handle,
-		displayName: entry.displayName,
-		connectedAt: entry.connectedAt
+		displayName: entry.displayName === null ? null : boundedOptionalString(entry.displayName, 512) ?? null,
+		connectedAt: boundedOptionalString(entry.connectedAt, 64) ?? ""
+	};
+	if (!isDid(did) || metadataDid && metadataDid !== did) return {
+		...base,
+		reason: "invalid_account_identity"
+	};
+	if (typeof entry.accessToken !== "string" || entry.accessToken.length === 0 || entry.accessToken.length > MAX_SESSION_BUNDLE_LENGTH) return {
+		...base,
+		reason: "invalid_session_bundle"
 	};
 	let bundle;
 	try {
@@ -165,22 +370,32 @@ function parseAccountEntry(entry) {
 			reason: "unparseable_session_bundle"
 		};
 	}
-	if (!bundle.accessJwt) return {
+	if (!isRecord(bundle)) return {
+		...base,
+		reason: "invalid_session_bundle"
+	};
+	const accessJwt = boundedString(bundle.accessJwt, MAX_ACCESS_JWT_LENGTH);
+	if (!accessJwt) return {
 		...base,
 		reason: "missing_access_jwt"
 	};
+	const bundleDid = boundedOptionalString(bundle.did, 256);
+	if (bundleDid !== void 0 && bundleDid !== did) return {
+		...base,
+		reason: "session_identity_mismatch"
+	};
 	try {
 		assertHttpsPdsHost(pdsHost);
-	} catch (err) {
+	} catch {
 		return {
 			...base,
-			reason: err instanceof Error ? err.message : "bad_pds_host"
+			reason: "invalid_pds_host"
 		};
 	}
 	return {
 		...base,
-		pdsHost,
-		accessJwt: bundle.accessJwt
+		pdsHost: new URL(pdsHost).origin,
+		accessJwt
 	};
 }
 /** Thrown when the PDS says the session is expired/invalid (drives one refresh). */
@@ -190,11 +405,13 @@ var BlueskyDriver = class BlueskyDriver {
 	toolPrefix = "bluesky";
 	capabilities = CAPABILITIES;
 	api;
-	accounts = /* @__PURE__ */ new Map();
-	byHandle = /* @__PURE__ */ new Map();
+	resolveHost;
+	accounts = [];
 	degraded = [];
-	constructor(api) {
+	selectors = /* @__PURE__ */ new Map();
+	constructor(api, resolveHost) {
 		this.api = api;
+		this.resolveHost = resolveHost;
 	}
 	/**
 	* Build a driver from the agent's connected Bluesky accounts. Zero accounts
@@ -202,27 +419,32 @@ var BlueskyDriver = class BlueskyDriver {
 	* accounts` / `bluesky_check_connection` register). Per-account parse
 	* failures are recorded as degraded rather than failing the whole driver.
 	*/
-	static async create(api) {
-		const driver = new BlueskyDriver(api);
+	static async create(api, options = {}) {
+		const driver = new BlueskyDriver(api, options.resolveHost ?? ((host) => dns.lookup(host, { all: true })));
 		const { accounts } = await api.getSocialAccounts("bluesky");
-		for (const entry of accounts) driver.ingest(entry);
+		driver.replaceAccounts(accounts);
 		return driver;
 	}
-	ingest(entry) {
-		const parsed = parseAccountEntry(entry);
-		if ("reason" in parsed) {
-			this.degraded.push(parsed);
-			return;
+	replaceAccounts(entries) {
+		this.accounts = [];
+		this.degraded = [];
+		this.selectors = /* @__PURE__ */ new Map();
+		for (const entry of entries.slice(0, MAX_ACCOUNTS)) {
+			const parsed = parseAccountEntry(entry);
+			if ("reason" in parsed) {
+				this.degraded.push(parsed);
+				continue;
+			}
+			this.accounts.push(parsed);
+			for (const selector of new Set([parsed.did, parsed.handle].filter(Boolean))) this.selectors.set(selector, this.selectors.has(selector) ? null : parsed);
 		}
-		this.accounts.set(parsed.did, parsed);
-		if (parsed.handle) this.byHandle.set(parsed.handle, parsed.did);
 	}
 	/** Resolve the `account` selector (DID or handle) to a usable account. */
 	resolve(account) {
 		if (!account) throw new Error("Missing required `account` argument. Call social_list_accounts to see connected Bluesky accounts and pass the handle or DID you want to target.");
-		const did = this.accounts.has(account) ? account : this.byHandle.get(account);
-		const acct = did ? this.accounts.get(did) : void 0;
-		if (!acct) {
+		const acct = this.selectors.get(account);
+		if (acct === null) throw new Error("Ambiguous account selector. Use a unique DID from social_list_accounts.");
+		if (acct === void 0) {
 			const degraded = this.degraded.find((d) => d.did === account || d.handle === account);
 			if (degraded) throw new Error(`Account "${account}" is connected but not usable (reason: ${degraded.reason}). Ask the user to reconnect this Bluesky account from the dashboard.`);
 			throw new Error(`Unknown account "${account}". Call social_list_accounts to see connected Bluesky accounts on this agent.`);
@@ -230,7 +452,7 @@ var BlueskyDriver = class BlueskyDriver {
 		return acct;
 	}
 	listAccounts() {
-		const usable = [...this.accounts.values()].map((a) => ({
+		const usable = this.accounts.map((a) => ({
 			accountIdentifier: a.did,
 			handle: a.handle,
 			displayName: a.displayName,
@@ -253,7 +475,7 @@ var BlueskyDriver = class BlueskyDriver {
 	* Honors a single `Retry-After` on 429. Never logs tokens.
 	*/
 	async xrpc(acct, method, nsid, opts = {}) {
-		assertHttpsPdsHost(acct.pdsHost);
+		await assertPublicPdsHost(acct.pdsHost, this.resolveHost);
 		const url = new URL(`${acct.pdsHost}/xrpc/${nsid}`);
 		for (const [k, v] of Object.entries(opts.query ?? {})) if (Array.isArray(v)) for (const item of v) url.searchParams.append(k, item);
 		else url.searchParams.set(k, v);
@@ -265,12 +487,14 @@ var BlueskyDriver = class BlueskyDriver {
 		const res = await fetch(url, {
 			method,
 			headers,
+			redirect: "error",
 			body: method === "POST" ? JSON.stringify(opts.body ?? {}) : void 0,
 			signal: AbortSignal.timeout(XRPC_TIMEOUT_MS)
 		});
 		if (res.status === 429 && !opts.retried429) {
 			const retryAfter = Number(res.headers.get("retry-after"));
 			const delayMs = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1e3 : 1e3;
+			await res.body?.cancel().catch(() => void 0);
 			await new Promise((r) => setTimeout(r, Math.min(delayMs, 3e4)));
 			return this.xrpc(acct, method, nsid, {
 				...opts,
@@ -278,7 +502,8 @@ var BlueskyDriver = class BlueskyDriver {
 			});
 		}
 		if (res.status === 401) {
-			if (opts.retriedAuth) throw new ExpiredTokenError(`Bluesky session invalid for ${acct.handle || acct.did} after refresh. Ask the user to reconnect.`);
+			await res.body?.cancel().catch(() => void 0);
+			if (opts.retriedAuth) throw new ExpiredTokenError("Bluesky session invalid after refresh. Ask the user to reconnect.");
 			const refreshed = await this.refreshAccount(acct.did);
 			return this.xrpc(refreshed, method, nsid, {
 				...opts,
@@ -287,10 +512,10 @@ var BlueskyDriver = class BlueskyDriver {
 			});
 		}
 		if (!res.ok) {
-			let detail = "";
+			let detail;
 			try {
-				const b = await res.json();
-				detail = b.error ?? b.message ?? "";
+				const body = await readProviderJson(res);
+				if (isRecord(body)) detail = boundedOptionalString(body.error, 128);
 			} catch {}
 			if (detail === "ExpiredToken" && !opts.retriedAuth) {
 				const refreshed = await this.refreshAccount(acct.did);
@@ -300,68 +525,67 @@ var BlueskyDriver = class BlueskyDriver {
 					retried429: false
 				});
 			}
-			throw new Error(`Bluesky ${nsid} failed: HTTP ${String(res.status)}${detail ? ` (${detail})` : ""}`);
+			throw new Error(`Bluesky request failed: HTTP ${String(res.status)}`);
 		}
-		return res.json();
+		return readProviderJson(res);
 	}
 	/** Delegate refresh to connect, then re-fetch accounts for the fresh jwt. */
 	async refreshAccount(did) {
 		await this.api.refreshSocialAccount("bluesky", did);
 		const { accounts } = await this.api.getSocialAccounts("bluesky");
-		const entry = accounts.find((a) => a.accountIdentifier === did);
-		if (entry) {
-			const parsed = parseAccountEntry(entry);
-			if (!("reason" in parsed)) {
-				this.accounts.set(parsed.did, parsed);
-				if (parsed.handle) this.byHandle.set(parsed.handle, parsed.did);
-				return parsed;
-			}
-		}
-		throw new ExpiredTokenError(`Could not resolve a usable Bluesky session for ${did} after refresh. Ask the user to reconnect.`);
+		this.replaceAccounts(accounts);
+		const refreshed = this.selectors.get(did);
+		if (refreshed) return refreshed;
+		throw new ExpiredTokenError("Could not resolve a usable Bluesky session after refresh. Ask the user to reconnect.");
 	}
 	async checkConnection(account) {
 		const acct = this.resolve(account);
 		const session = await this.xrpc(acct, "GET", "com.atproto.server.getSession");
+		if (!isRecord(session)) throw new Error("Invalid Bluesky session response");
+		const did = boundedString(session.did, 256);
+		const handle = boundedString(session.handle, 256);
+		if (!did || !handle || did !== acct.did) throw new Error("Invalid Bluesky session response");
 		return { data: {
 			account: acct.handle || acct.did,
 			connected: true,
-			did: session.did,
-			handle: session.handle
+			did,
+			handle
 		} };
 	}
 	async postText(args) {
 		const acct = this.resolve(args.account);
-		const len = graphemeLen(args.text);
-		if (len > POST_TEXT_MAX) throw new Error(`Post text is ${String(len)} characters; Bluesky's limit is ${String(POST_TEXT_MAX)}. Shorten it.`);
+		validatePostText(args.text, "Post");
 		const record = {
 			$type: "app.bsky.feed.post",
 			text: args.text,
 			createdAt: (/* @__PURE__ */ new Date()).toISOString(),
 			facets: detectLinkFacets(args.text)
 		};
-		const out = await this.xrpc(acct, "POST", "com.atproto.repo.createRecord", { body: {
-			repo: acct.did,
-			collection: "app.bsky.feed.post",
-			record
-		} });
 		return { data: {
-			uri: out.uri,
-			cid: out.cid,
+			...parseCreatedPost(await this.xrpc(acct, "POST", "com.atproto.repo.createRecord", { body: {
+				repo: acct.did,
+				collection: POST_COLLECTION,
+				record
+			} }), acct.did),
 			account: acct.handle || acct.did
 		} };
 	}
 	async reply(args) {
 		const acct = this.resolve(args.account);
-		const len = graphemeLen(args.text);
-		if (len > POST_TEXT_MAX) throw new Error(`Reply text is ${String(len)} characters; Bluesky's limit is ${String(POST_TEXT_MAX)}. Shorten it.`);
+		validatePostText(args.text, "Reply");
+		parsePostUri(args.parent);
 		const parent = await this.xrpc(acct, "GET", "app.bsky.feed.getPostThread", { query: { uri: args.parent } });
-		const parentPost = parent.thread?.post;
-		if (!parentPost?.uri || !parentPost.cid) throw new Error(`Could not resolve parent post "${args.parent}" for reply.`);
+		const thread = isRecord(parent) && isRecord(parent.thread) ? parent.thread : void 0;
+		const parentPost = thread && isRecord(thread.post) ? thread.post : void 0;
+		const parentUri = parentPost && boundedString(parentPost.uri, 2048);
+		const parentCid = parentPost && boundedString(parentPost.cid, 256);
+		if (!parentUri || !parentCid || parentUri !== args.parent) throw new Error("Could not resolve parent post for reply.");
+		parsePostUri(parentUri);
 		const parentRef = {
-			uri: parentPost.uri,
-			cid: parentPost.cid
+			uri: parentUri,
+			cid: parentCid
 		};
-		const rootRef = deriveRoot(parent.thread) ?? parentRef;
+		const rootRef = deriveRoot(thread) ?? parentRef;
 		const record = {
 			$type: "app.bsky.feed.post",
 			text: args.text,
@@ -372,53 +596,55 @@ var BlueskyDriver = class BlueskyDriver {
 				parent: parentRef
 			}
 		};
-		const out = await this.xrpc(acct, "POST", "com.atproto.repo.createRecord", { body: {
-			repo: acct.did,
-			collection: "app.bsky.feed.post",
-			record
-		} });
 		return { data: {
-			uri: out.uri,
-			cid: out.cid,
+			...parseCreatedPost(await this.xrpc(acct, "POST", "com.atproto.repo.createRecord", { body: {
+				repo: acct.did,
+				collection: POST_COLLECTION,
+				record
+			} }), acct.did),
 			account: acct.handle || acct.did
 		} };
 	}
 	async getPost(args) {
 		const acct = this.resolve(args.account);
-		return { data: { posts: (await this.xrpc(acct, "GET", "app.bsky.feed.getPosts", { query: { uris: [args.post] } })).posts ?? [] } };
+		parsePostUri(args.post);
+		return { data: { posts: projectPosts(await this.xrpc(acct, "GET", "app.bsky.feed.getPosts", { query: { uris: [args.post] } }), 1) } };
 	}
 	async getMetrics(args) {
 		const acct = this.resolve(args.account);
-		const post = (await this.xrpc(acct, "GET", "app.bsky.feed.getPosts", { query: { uris: [args.post] } })).posts?.[0];
-		if (!post) throw new Error(`No post found for "${args.post}".`);
+		parsePostUri(args.post);
+		const post = projectPosts(await this.xrpc(acct, "GET", "app.bsky.feed.getPosts", { query: { uris: [args.post] } }), 1).at(0);
+		if (post?.uri !== args.post) throw new Error("No post found.");
 		return { data: {
 			uri: post.uri,
-			likes: post.likeCount ?? 0,
-			reposts: post.repostCount ?? 0,
-			replies: post.replyCount ?? 0,
-			quotes: post.quoteCount ?? 0
+			likes: post.likeCount,
+			reposts: post.repostCount,
+			replies: post.replyCount,
+			quotes: post.quoteCount
 		} };
 	}
 	async listNotifications(args) {
 		const acct = this.resolve(args.account);
 		const query = {};
 		if (typeof args.limit === "number") query.limit = String(Math.min(Math.max(args.limit, 1), 100));
-		return { data: { notifications: (await this.xrpc(acct, "GET", "app.bsky.notification.listNotifications", { query })).notifications ?? [] } };
+		return { data: { notifications: projectNotifications(await this.xrpc(acct, "GET", "app.bsky.notification.listNotifications", { query }), args.limit ?? 50) } };
 	}
 	async search(args) {
 		const acct = this.resolve(args.account);
-		const query = { q: args.query };
+		const searchQuery = args.query.trim();
+		if (searchQuery.length === 0 || searchQuery.length > 512) throw new Error("Search query must contain 1-512 characters.");
+		const query = { q: searchQuery };
 		if (typeof args.limit === "number") query.limit = String(Math.min(Math.max(args.limit, 1), 100));
-		return { data: { posts: (await this.xrpc(acct, "GET", "app.bsky.feed.searchPosts", { query })).posts ?? [] } };
+		return { data: { posts: projectPosts(await this.xrpc(acct, "GET", "app.bsky.feed.searchPosts", { query }), args.limit ?? 25) } };
 	}
 	async deletePost(args) {
 		const acct = this.resolve(args.account);
-		const rkey = rkeyFromUri(args.post);
-		if (!rkey) throw new Error(`Could not parse a record key from "${args.post}".`);
+		const parsed = parsePostUri(args.post);
+		if (parsed.repo !== acct.did) throw new Error("The post URI does not belong to the selected account.");
 		await this.xrpc(acct, "POST", "com.atproto.repo.deleteRecord", { body: {
 			repo: acct.did,
-			collection: "app.bsky.feed.post",
-			rkey
+			collection: POST_COLLECTION,
+			rkey: parsed.rkey
 		} });
 		return { data: {
 			deleted: true,
@@ -436,11 +662,112 @@ const graphemeSegmenter = new Intl.Segmenter(void 0, { granularity: "grapheme" }
 function graphemeLen(text) {
 	return [...graphemeSegmenter.segment(text)].length;
 }
-/** Extract the record key (last path segment) from an at:// URI. */
-function rkeyFromUri(uri) {
-	const parts = uri.split("/");
-	const last = parts[parts.length - 1];
-	return last && parts.length >= 3 ? last : null;
+function validatePostText(text, label) {
+	const graphemes = graphemeLen(text);
+	if (graphemes === 0) throw new Error(`${label} text must not be empty.`);
+	if (graphemes > POST_GRAPHEME_MAX) throw new Error(`${label} text is ${String(graphemes)} characters; Bluesky's limit is ${String(POST_GRAPHEME_MAX)}. Shorten it.`);
+	if (new TextEncoder().encode(text).byteLength > POST_UTF8_MAX) throw new Error(`${label} text exceeds Bluesky's UTF-8 byte limit. Shorten it.`);
+}
+function isDid(value) {
+	return /^did:[a-z0-9]+:[A-Za-z0-9._:%-]+$/u.test(value);
+}
+/** Parse an exact AT post URI, rejecting a foreign collection or extra URL parts. */
+function parsePostUri(uri) {
+	if (uri.length === 0 || uri.length > 2048 || uri.includes("?") || uri.includes("#")) throw new Error("Invalid Bluesky post URI.");
+	const match = /^at:\/\/([^/]+)\/app\.bsky\.feed\.post\/([^/]+)$/u.exec(uri);
+	if (!match) throw new Error("Invalid Bluesky post URI.");
+	const [, repo, rkey] = match;
+	if (!isDid(repo) && !/^(?=.{1,253}$)[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?$/u.test(repo) || !/^[A-Za-z0-9._~:@!$&'()*+,;=-]{1,512}$/u.test(rkey)) throw new Error("Invalid Bluesky post URI.");
+	return {
+		repo,
+		rkey
+	};
+}
+function projectPosts(value, maxItems) {
+	if (!isRecord(value) || !Array.isArray(value.posts)) return [];
+	const posts = [];
+	for (const raw of value.posts.slice(0, Math.min(Math.max(maxItems, 0), 100))) {
+		const projected = projectPost(raw);
+		if (projected) posts.push(projected);
+	}
+	return posts;
+}
+function projectPost(value) {
+	if (!isRecord(value)) return void 0;
+	const uri = boundedString(value.uri, 2048);
+	if (!uri) return void 0;
+	try {
+		parsePostUri(uri);
+	} catch {
+		return;
+	}
+	const record = isRecord(value.record) ? value.record : void 0;
+	const author = projectAuthor(value.author);
+	return {
+		uri,
+		...boundedOptionalString(value.cid, 256) ? { cid: String(value.cid) } : {},
+		...author ? { author } : {},
+		...record && boundedOptionalString(record.text, POST_UTF8_MAX) ? { text: String(record.text) } : {},
+		...record && boundedOptionalString(record.createdAt, 64) ? { createdAt: String(record.createdAt) } : {},
+		...boundedOptionalString(value.indexedAt, 64) ? { indexedAt: String(value.indexedAt) } : {},
+		likeCount: nonNegativeCount(value.likeCount),
+		repostCount: nonNegativeCount(value.repostCount),
+		replyCount: nonNegativeCount(value.replyCount),
+		quoteCount: nonNegativeCount(value.quoteCount)
+	};
+}
+function projectAuthor(value) {
+	if (!isRecord(value)) return void 0;
+	const did = boundedString(value.did, 256);
+	if (!did || !isDid(did)) return void 0;
+	const handle = boundedOptionalString(value.handle, 256);
+	const displayName = boundedOptionalString(value.displayName, 512);
+	return {
+		did,
+		...handle ? { handle } : {},
+		...displayName ? { displayName } : {}
+	};
+}
+function projectNotifications(value, maxItems) {
+	if (!isRecord(value) || !Array.isArray(value.notifications)) return [];
+	const notifications = [];
+	for (const raw of value.notifications.slice(0, Math.min(Math.max(maxItems, 0), 100))) {
+		if (!isRecord(raw)) continue;
+		const reason = boundedString(raw.reason, 64);
+		const indexedAt = boundedString(raw.indexedAt, 64);
+		const author = projectAuthor(raw.author);
+		if (!reason || !indexedAt || !author) continue;
+		const uri = boundedOptionalString(raw.uri, 2048);
+		if (uri && !isAtRecordUri(uri)) continue;
+		const reasonSubject = boundedOptionalString(raw.reasonSubject, 2048);
+		if (reasonSubject && !isAtRecordUri(reasonSubject)) continue;
+		notifications.push({
+			reason,
+			indexedAt,
+			author,
+			isRead: raw.isRead === true,
+			...uri ? { uri } : {},
+			...reasonSubject ? { reasonSubject } : {}
+		});
+	}
+	return notifications;
+}
+function isAtRecordUri(value) {
+	if (value.includes("?") || value.includes("#")) return false;
+	const match = /^at:\/\/([^/]+)\/([a-z][a-z0-9.-]{0,253})\/([^/]+)$/u.exec(value);
+	if (!match) return false;
+	const [, repo, , rkey] = match;
+	return (isDid(repo) || /^(?=.{1,253}$)[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?$/u.test(repo)) && /^[A-Za-z0-9._~:@!$&'()*+,;=-]{1,512}$/u.test(rkey);
+}
+function parseCreatedPost(value, expectedDid) {
+	if (!isRecord(value)) throw new Error("Invalid Bluesky create-record response");
+	const uri = boundedString(value.uri, 2048);
+	const cid = boundedString(value.cid, 256);
+	if (!uri || !cid || parsePostUri(uri).repo !== expectedDid) throw new Error("Invalid Bluesky create-record response");
+	return {
+		uri,
+		cid
+	};
 }
 /**
 * Best-effort thread-root ref extraction from a getPostThread response.
@@ -454,11 +781,25 @@ function rkeyFromUri(uri) {
 */
 function deriveRoot(thread) {
 	if (!thread) return void 0;
-	const root = thread.post?.record?.reply?.root;
-	if (root?.uri && root.cid) return {
-		uri: root.uri,
-		cid: root.cid
-	};
+	const post = isRecord(thread.post) ? thread.post : void 0;
+	const record = post && isRecord(post.record) ? post.record : void 0;
+	const reply = record && isRecord(record.reply) ? record.reply : void 0;
+	const root = reply && isRecord(reply.root) ? reply.root : void 0;
+	const uri = root && boundedString(root.uri, 2048);
+	const cid = root && boundedString(root.cid, 256);
+	if (uri && cid) {
+		parsePostUri(uri);
+		return {
+			uri,
+			cid
+		};
+	}
+}
+//#endregion
+//#region src/execution.ts
+/** Pure direct-execution check kept separate so importing the CLI stays inert. */
+function isDirectExecution(moduleUrl, argvEntry = process.argv.at(1)) {
+	return typeof argvEntry === "string" && pathToFileURL(resolve(argvEntry)).href === moduleUrl;
 }
 //#endregion
 //#region src/tools.ts
@@ -492,21 +833,12 @@ function deriveRoot(thread) {
 * names `github_list_accounts` alongside its GitHub-specific tools.
 */
 function ok(data) {
-	return { content: [{
-		type: "text",
-		text: JSON.stringify(data, null, 2)
-	}] };
+	return toolResult(data);
 }
-function fail(err) {
-	return {
-		content: [{
-			type: "text",
-			text: JSON.stringify({ error: err instanceof Error ? err.message : String(err) }, null, 2)
-		}],
-		isError: true
-	};
+function fail() {
+	return toolError();
 }
-const accountField = z.string().describe("The connected account to act as — the handle or DID from social_list_accounts. Selects which OAuth identity makes the call (Pattern A).");
+const accountField = z.string().trim().min(1).max(256).describe("The connected account to act as — the handle or DID from social_list_accounts. Selects which OAuth identity makes the call (Pattern A).");
 /**
 * The one table both registration and descriptor-building derive from. The
 * `capability` field is BOTH the `SocialCapabilities` flag and the same-named
@@ -520,7 +852,7 @@ const ACTION_TOOL_SPECS = [
 		description: "Publish a text post as the selected account. Links in the text are auto-detected and made clickable. Enforces the platform's character limit.",
 		inputSchema: {
 			account: accountField,
-			text: z.string().describe("The post body.")
+			text: z.string().min(1).max(3e3).describe("The non-empty post body.")
 		}
 	},
 	{
@@ -529,8 +861,8 @@ const ACTION_TOOL_SPECS = [
 		description: "Reply to a post as the selected account. Pass the parent post's URI/id; the thread root is resolved automatically.",
 		inputSchema: {
 			account: accountField,
-			parent: z.string().describe("URI/id of the post being replied to."),
-			text: z.string().describe("The reply body.")
+			parent: z.string().min(1).max(2048).describe("AT URI of the post being replied to."),
+			text: z.string().min(1).max(3e3).describe("The non-empty reply body.")
 		}
 	},
 	{
@@ -539,7 +871,7 @@ const ACTION_TOOL_SPECS = [
 		description: "Fetch a post by its URI/id as the selected account.",
 		inputSchema: {
 			account: accountField,
-			post: z.string().describe("URI/id of the post to fetch.")
+			post: z.string().min(1).max(2048).describe("AT URI of the post to fetch.")
 		}
 	},
 	{
@@ -548,7 +880,7 @@ const ACTION_TOOL_SPECS = [
 		description: "Get like / repost / reply / quote counts for a post.",
 		inputSchema: {
 			account: accountField,
-			post: z.string().describe("URI/id of the post to measure.")
+			post: z.string().min(1).max(2048).describe("AT URI of the post to measure.")
 		}
 	},
 	{
@@ -566,7 +898,7 @@ const ACTION_TOOL_SPECS = [
 		description: "Search posts as the selected account.",
 		inputSchema: {
 			account: accountField,
-			query: z.string().describe("Search query."),
+			query: z.string().trim().min(1).max(512).describe("Search query."),
 			limit: z.coerce.number().int().min(1).max(100).optional().describe("Max results (1-100).")
 		}
 	},
@@ -576,7 +908,7 @@ const ACTION_TOOL_SPECS = [
 		description: "Delete a post the selected account authored, by its URI/id.",
 		inputSchema: {
 			account: accountField,
-			post: z.string().describe("URI/id of the post to delete.")
+			post: z.string().min(1).max(2048).describe("AT URI of the selected account's post to delete.")
 		}
 	}
 ];
@@ -611,8 +943,8 @@ function registerTools(server, driver) {
 	}, async (args) => {
 		try {
 			return ok((await driver.checkConnection(args.account)).data);
-		} catch (err) {
-			return fail(err);
+		} catch {
+			return fail();
 		}
 	});
 	for (const spec of ACTION_TOOL_SPECS) {
@@ -621,7 +953,7 @@ function registerTools(server, driver) {
 		register(`${p}_${spec.suffix}`, {
 			description: spec.description,
 			inputSchema: spec.inputSchema
-		}, (args) => method(args).then((r) => ok(r.data), (err) => fail(err)));
+		}, (args) => method(args).then((r) => ok(r.data), () => fail()));
 	}
 }
 /**
@@ -686,9 +1018,12 @@ const DISCOVERY_TOOL_NAME = "social_list_accounts";
 * Pattern A: every credential-touching tool requires an `account` selector;
 * `assertPatternA()` runs at startup so a forgotten selector fails closed.
 */
+const packageJson = createRequire(import.meta.url)("../package.json");
+const SERVER_VERSION = typeof packageJson.version === "string" ? packageJson.version : "0.0.0";
 function log(msg) {
 	process.stderr.write(`[social-mcp] ${msg}\n`);
 }
+var SafeStartupError = class extends Error {};
 /**
 * Per-provider driver factories. Adding a platform = add a `SocialDriver`
 * implementation and register its factory here (plus `SUPPORTED_PROVIDERS` in
@@ -700,39 +1035,62 @@ const DRIVER_FACTORIES = { bluesky: (api) => BlueskyDriver.create(api) };
 function createDriver(provider, api) {
 	return DRIVER_FACTORIES[provider](api);
 }
-async function main() {
-	const parsed = parseProviderArg(process.argv.slice(2));
-	if (!parsed.ok) {
-		log(`Fatal: ${parsed.error}`);
-		process.exit(1);
-	}
+async function runSocialServer(argv = process.argv.slice(2), dependencies = {}) {
+	const parsed = parseProviderArg(argv);
+	if (!parsed.ok) throw new SafeStartupError(parsed.error);
 	const provider = parsed.provider;
-	const { apiKey, apiUrl } = resolveConfig();
-	const driver = await createDriver(provider, new AgentApiClient({
+	const { apiKey, apiUrl } = (dependencies.resolveRuntimeConfig ?? resolveConfig)();
+	const api = dependencies.createApiClient ? dependencies.createApiClient({
+		apiKey,
+		apiUrl
+	}) : new AgentApiClient({
 		apiKey,
 		apiUrl
-	}));
+	});
+	const driver = await (dependencies.createProviderDriver ?? createDriver)(provider, api);
 	const usable = driver.listAccounts().filter((a) => a.connected).length;
 	if (usable === 0) log(`No ${provider} accounts connected — server will start with ${DISCOVERY_TOOL_NAME} and ${driver.toolPrefix}_check_connection only`);
 	const server = new McpServer({
 		name: "social-mcp-server",
-		version: "0.1.0"
+		version: SERVER_VERSION
 	});
 	registerTools(server, driver);
 	assertPatternA(buildPatternADescriptors(driver), {
 		selector: "account",
 		exempt: [DISCOVERY_TOOL_NAME]
 	});
-	for (const signal of ["SIGTERM", "SIGINT"]) process.on(signal, () => {
-		process.exit(0);
-	});
-	const transport = new StdioServerTransport();
+	const transport = dependencies.createTransport?.() ?? new StdioServerTransport();
 	await server.connect(transport);
+	let stopping = false;
+	const shutdown = async () => {
+		if (stopping) return;
+		stopping = true;
+		for (const signal of ["SIGTERM", "SIGINT"]) process.off(signal, signalHandlers[signal]);
+		await server.close();
+	};
+	const signalHandlers = {
+		SIGTERM: () => void shutdown().catch(() => {
+			process.exitCode = 1;
+		}),
+		SIGINT: () => void shutdown().catch(() => {
+			process.exitCode = 1;
+		})
+	};
+	for (const signal of ["SIGTERM", "SIGINT"]) process.once(signal, signalHandlers[signal]);
 	log(`${provider} MCP server running with ${String(usable)} connected account(s) and Pattern A selector enforcement`);
+	return {
+		server,
+		shutdown
+	};
+}
+async function main() {
+	try {
+		await runSocialServer();
+	} catch (error) {
+		log(error instanceof SafeStartupError ? `Fatal: ${error.message}` : "Fatal: social MCP server failed to start");
+		process.exitCode = 1;
+	}
 }
-main().catch((err) => {
-	log(`Fatal: ${err instanceof Error ? err.message : String(err)}`);
-	process.exit(1);
-});
+if (isDirectExecution(import.meta.url)) main();
 //#endregion
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfe.ai/social-mcp",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Social MCP server — post, engage, and read on connected social accounts (Bluesky today; X / Meta / Threads / LinkedIn / Pinterest / TikTok / Reddit / YouTube on the approval-gated roster) via Alfe Connect credentials (Pattern A multi-account, provider selected via --provider)",
   "type": "module",
   "main": "./dist/server.js",
@@ -14,14 +14,15 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.0.5",
-    "@alfe.ai/agent-api-client": "0.13.0",
-    "@alfe.ai/config": "0.3.0",
-    "@alfe.ai/mcp-bundler": "0.4.0"
+    "@alfe.ai/agent-api-client": "0.15.0",
+    "@alfe.ai/config": "0.4.1",
+    "@alfe.ai/mcp-bundler": "0.4.1"
   },
   "license": "UNLICENSED",
   "homepage": "https://alfe.ai",