Skip to content

armgit / mso

Public Imported from GitHub
0

Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.

refactor(infra): split composio session into contract, store and orchestration (#145)

Abdurrahman Fakhrul15d3da97b6d0
diff --git a/lib/infra/composio-session-contract.ts b/lib/infra/composio-session-contract.ts
new file mode 100644
index 00000000..86d20bca
--- /dev/null
+++ b/lib/infra/composio-session-contract.ts
@@ -0,0 +1,78 @@
+import { normalizeMcpEndpoint } from "./mcp-policy";
+import { obj } from "./http";
+import { COMPOSIO_API_BASE, COMPOSIO_CONNECT_KEY_MESSAGE } from "./composio";
+import { IntegrationError } from "./identity";
+
+/**
+ * Per-end-user Composio session and its hosted MCP endpoint.
+ *
+ * Verified against the live Platform API surface (`POST /api/v3.1/tool_router/session`
+ * in `backend.composio.dev/api/v3.1/openapi.json`, spec 3.1.0):
+ *
+ * - The REQUEST schema has no `mcp` field (props: user_id, toolkits, auth_configs,
+ * connected_accounts, instant, manage_connections, tools, tags, workbench,
+ * proxy_execute, multi_account, experimental, preload, hooks, search, execute).
+ * `mcp: true` in the SDKs is client-side sugar only.
+ * - The 201 RESPONSE carries `mcp: {type, url}` and no `headers` member.
+ *
+ * Therefore the MCP endpoint has no credential of its own to hand out: the client
+ * credential IS the session credential. `docs/sessions-via-mcp` says
+ * `session.mcp.headers` holds exactly "the credential the SDK used to create or load
+ * the session, and nothing else. No other default header and no ambient
+ * COMPOSIO_API_KEY is copied in", and maps it per key kind: project → `x-api-key`,
+ * user → `x-user-api-key`, org → `x-org-api-key`. That is byte-for-byte what
+ * `composioAuthHeader` returns for the credential that authenticated this very create
+ * call, so the composed header is derived from that one `auth` object - never from an
+ * environment variable, never re-resolved, never a different key. If a future API
+ * version does return `mcp.headers`, those win verbatim.
+ *
+ * `mcpHeaders` stays server-side: the HTTP route returns the URL only.
+ */
+export const SESSION_URL = `${COMPOSIO_API_BASE}/tool_router/session`;
+/** Same allowlist as Composio redirect links, plus the host the spec example returns. */
+export const COMPOSIO_MCP_HOSTS = ["connect.composio.dev", "backend.composio.dev", "platform.composio.dev", "app.composio.dev"];
+const MAX_HEADERS = 32;
+const HEADER_NAME = /^[A-Za-z0-9!#$%&'*+.^_`|~-]{1,64}$/;
+
+export type ComposioSession = {
+ sessionId: string;
+ mcpUrl: string;
+ /** The credential the SDK exports for this session URL: composed from the key that authenticated the create call. Server-side only. */
+ mcpHeaders: Record<string, string>;
+ expiresAt?: number;
+};
+
+/** One helper for every message this module throws: an upstream body can echo a credential. */
+export function redactComposioMessage(message: string, secrets: (string | undefined)[]): string {
+ let out = message;
+ for (const secret of secrets) if (secret && secret.length >= 6) out = out.split(secret).join("[redacted]");
+ return out;
+}
+
+export function connectKeyRefusal(): IntegrationError {
+ const error = new IntegrationError("composio_connect_key_wrong_provider", 409);
+ error.message = COMPOSIO_CONNECT_KEY_MESSAGE;
+ return error;
+}
+
+export function headerMap(value: unknown): Record<string, string> {
+ const raw = obj(value);
+ const entries = Object.entries(raw);
+ if (entries.length > MAX_HEADERS) throw new IntegrationError("invalid_composio_session_headers", 502);
+ const headers: Record<string, string> = {};
+ for (const [name, entry] of entries) {
+ if (!HEADER_NAME.test(name) || typeof entry !== "string" || !entry || entry.length > 4096 || /[\r\n\0]/.test(entry)) {
+ throw new IntegrationError("invalid_composio_session_headers", 502);
+ }
+ headers[name] = entry;
+ }
+ return headers;
+}
+
+/** Fail closed on a session URL pointing anywhere the session could not live. */
+export function composioMcpUrl(raw: string): string {
+ let href: string;
+ try { href = normalizeMcpEndpoint(raw); } catch { throw new IntegrationError("invalid_composio_mcp_endpoint", 502); }
+ if (!COMPOSIO_MCP_HOSTS.includes(new URL(href).hostname)) throw new IntegrationError("invalid_composio_mcp_host", 502);
+ return href;
+}
diff --git a/lib/infra/composio-session-store.ts b/lib/infra/composio-session-store.ts
new file mode 100644
index 00000000..7d3eb4de
--- /dev/null
+++ b/lib/infra/composio-session-store.ts
@@ -0,0 +1,95 @@
+import { constants, promises as fs } from "node:fs";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { pinSecurityStorePath } from "@/lib/security-store-path";
+import { normalizeMcpEndpoint } from "./mcp-policy";
+import { obj } from "./http";
+import { INFRA_STORE_PATH } from "./connection-storage";
+import { IntegrationError } from "./identity";
+import { COMPOSIO_MCP_HOSTS, headerMap, type ComposioSession } from "./composio-session-contract";
+
+const MAX_STORE_BYTES = 256 * 1024;
+const KEY_PART = /^[A-Za-z0-9:_.-]{1,200}$/;
+
+export type StoredSession = ComposioSession & { instanceId: string; userUid: string; createdAt: number };
+export type Store = { version: 1; sessions: Record<string, StoredSession> };
+
+/** Owner-only, beside `infra-providers.json`: 0700 parent, 0600 file, O_NOFOLLOW, uid-checked. */
+export const composioSessionStorePath = () => path.join(path.dirname(INFRA_STORE_PATH), "composio-sessions.json");
+
+function parseStore(value: unknown): Store {
+ const raw = obj(value);
+ const bad = (): never => { throw new IntegrationError("invalid_composio_session_store"); };
+ if (raw.version !== 1 || !raw.sessions || typeof raw.sessions !== "object" || Array.isArray(raw.sessions)) bad();
+ const sessions: Record<string, StoredSession> = {};
+ for (const [key, entry] of Object.entries(raw.sessions as Record<string, unknown>)) {
+ const row = obj(entry);
+ const keyParts = key.split(":");
+ if (keyParts.length !== 2 || keyParts.some((part) => !KEY_PART.test(part))) bad();
+ const { sessionId, instanceId, userUid, createdAt, expiresAt, mcpUrl: rawUrl } = row;
+ const id = typeof sessionId === "string" && /^[A-Za-z0-9_-]{1,200}$/.test(sessionId) ? sessionId : bad();
+ const instance = typeof instanceId === "string" ? instanceId : bad();
+ const uid = typeof userUid === "string" ? userUid : bad();
+ const created = Number.isSafeInteger(createdAt) ? createdAt as number : bad();
+ let mcpUrl: string;
+ try {
+ mcpUrl = normalizeMcpEndpoint(String(rawUrl ?? ""));
+ if (!COMPOSIO_MCP_HOSTS.includes(new URL(mcpUrl).hostname)) return bad();
+ } catch { return bad(); }
+ sessions[key] = {
+ sessionId: id, mcpUrl, mcpHeaders: headerMap(row.mcpHeaders),
+ instanceId: instance, userUid: uid, createdAt: created,
+ ...(Number.isFinite(expiresAt) ? { expiresAt: Number(expiresAt) } : {}),
+ };
+ }
+ return { version: 1, sessions };
+}
+
+export async function readComposioSessions(): Promise<Store> {
+ const pinned = await pinSecurityStorePath(composioSessionStorePath());
+ let handle;
+ try {
+ handle = await fs.open(pinned.file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+ const stat = await handle.stat();
+ if (!stat.isFile() || stat.size < 1 || stat.size > MAX_STORE_BYTES || (stat.mode & 0o077) || stat.uid !== process.getuid?.()) throw new IntegrationError("unsafe_composio_session_store");
+ return parseStore(JSON.parse(await handle.readFile("utf8")));
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") return { version: 1, sessions: {} };
+ if (error instanceof IntegrationError) throw error;
+ throw new IntegrationError("invalid_composio_session_store");
+ } finally { await handle?.close(); await pinned.directory.close(); }
+}
+
+export async function writeComposioSessions(store: Store): Promise<void> {
+ const pinned = await pinSecurityStorePath(composioSessionStorePath());
+ const text = JSON.stringify(parseStore(store), null, 2) + "\n";
+ try {
+ if (Buffer.byteLength(text) > MAX_STORE_BYTES) throw new IntegrationError("composio_session_store_capacity", 409);
+ const temporary = `${pinned.file}.${randomUUID()}.tmp`;
+ try {
+ const handle = await fs.open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+ try { await handle.writeFile(text); await handle.sync(); } finally { await handle.close(); }
+ await fs.rename(temporary, pinned.file);
+ } finally { await fs.unlink(temporary).catch(() => undefined); }
+ await pinned.directory.sync();
+ } finally { await pinned.directory.close(); }
+}
+
+export const storeKey = (instanceId: string, userUid: string) => {
+ if (!KEY_PART.test(instanceId) || !KEY_PART.test(userUid) || instanceId.includes(":") || userUid.includes(":")) throw new IntegrationError("invalid_composio_session_key");
+ return `${instanceId}:${userUid}`;
+};
+
+/** Never returns another MSO user's session: the key is (instance, credential-owner uid). */
+export async function readComposioSession(instanceId: string, userUid: string): Promise<StoredSession | null> {
+ const key = storeKey(instanceId, userUid);
+ const row = (await readComposioSessions()).sessions[key];
+ if (!row || row.instanceId !== instanceId || row.userUid !== userUid) return null;
+ if (row.expiresAt !== undefined && row.expiresAt <= Date.now()) return null;
+ return row;
+}
+
+export function composioRemoteUserId(instanceId: string, userUid: string): string {
+ storeKey(instanceId, userUid);
+ return `mso:${instanceId}:${userUid}`;
+}
diff --git a/lib/infra/composio-session.ts b/lib/infra/composio-session.ts
index d2d439ff..f491b58e 100644
--- a/lib/infra/composio-session.ts
+++ b/lib/infra/composio-session.ts
@@ -1,100 +1,27 @@
-import { constants, promises as fs } from "node:fs";
-import { randomUUID } from "node:crypto";
-import path from "node:path";
-import { pinSecurityStorePath } from "@/lib/security-store-path";
import { withSecurityStoreLock } from "@/lib/security-store-lock";
-import { normalizeMcpEndpoint } from "./mcp-policy";
import { request, obj } from "./http";
-import { COMPOSIO_API_BASE, COMPOSIO_CONNECT_KEY_MESSAGE, composioAuthHeader } from "./composio";
-import { INFRA_STORE_PATH, readIntegrationState } from "./connection-storage";
+import { composioAuthHeader } from "./composio";
+import { readIntegrationState } from "./connection-storage";
import { IntegrationError, resolveUser } from "./identity";
import { currentIntegrationSelection } from "./connection-service";
import type { InfraProviderValues } from "./types";
-
-/**
- * Per-end-user Composio session and its hosted MCP endpoint.
- *
- * Verified against the live Platform API surface (`POST /api/v3.1/tool_router/session`
- * in `backend.composio.dev/api/v3.1/openapi.json`, spec 3.1.0):
- *
- * - The REQUEST schema has no `mcp` field (props: user_id, toolkits, auth_configs,
- * connected_accounts, instant, manage_connections, tools, tags, workbench,
- * proxy_execute, multi_account, experimental, preload, hooks, search, execute).
- * `mcp: true` in the SDKs is client-side sugar only.
- * - The 201 RESPONSE carries `mcp: {type, url}` and no `headers` member.
- *
- * Therefore the MCP endpoint has no credential of its own to hand out: the client
- * credential IS the session credential. `docs/sessions-via-mcp` says
- * `session.mcp.headers` holds exactly "the credential the SDK used to create or load
- * the session, and nothing else. No other default header and no ambient
- * COMPOSIO_API_KEY is copied in", and maps it per key kind: project → `x-api-key`,
- * user → `x-user-api-key`, org → `x-org-api-key`. That is byte-for-byte what
- * `composioAuthHeader` returns for the credential that authenticated this very create
- * call, so the composed header is derived from that one `auth` object - never from an
- * environment variable, never re-resolved, never a different key. If a future API
- * version does return `mcp.headers`, those win verbatim.
- *
- * `mcpHeaders` stays server-side: the HTTP route returns the URL only.
- */
-const SESSION_URL = `${COMPOSIO_API_BASE}/tool_router/session`;
-/** Same allowlist as Composio redirect links, plus the host the spec example returns. */
-export const COMPOSIO_MCP_HOSTS = ["connect.composio.dev", "backend.composio.dev", "platform.composio.dev", "app.composio.dev"];
-const MAX_STORE_BYTES = 256 * 1024;
-const MAX_HEADERS = 32;
-const HEADER_NAME = /^[A-Za-z0-9!#$%&'*+.^_`|~-]{1,64}$/;
-const KEY_PART = /^[A-Za-z0-9:_.-]{1,200}$/;
-
-export type ComposioSession = {
- sessionId: string;
- mcpUrl: string;
- /** The credential the SDK exports for this session URL: composed from the key that authenticated the create call. Server-side only. */
- mcpHeaders: Record<string, string>;
- expiresAt?: number;
-};
+import {
+ SESSION_URL, composioMcpUrl, connectKeyRefusal, headerMap, redactComposioMessage, type ComposioSession,
+} from "./composio-session-contract";
+import {
+ composioRemoteUserId, composioSessionStorePath, readComposioSession, readComposioSessions, storeKey, writeComposioSessions,
+} from "./composio-session-store";
+
+// Public surface kept: the verified contract facts, host allowlist and store helpers live in
+// composio-session-contract.ts / composio-session-store.ts but stay importable from here.
+export { COMPOSIO_MCP_HOSTS, redactComposioMessage, type ComposioSession } from "./composio-session-contract";
+export {
+ composioRemoteUserId, composioSessionStorePath, readComposioSession, readComposioSessions,
+ type StoredSession, type Store,
+} from "./composio-session-store";
export type ComposioSessionResolution = ComposioSession & { reused: boolean; user: string };
-type StoredSession = ComposioSession & { instanceId: string; userUid: string; createdAt: number };
-type Store = { version: 1; sessions: Record<string, StoredSession> };
-
-/** Owner-only, beside `infra-providers.json`: 0700 parent, 0600 file, O_NOFOLLOW, uid-checked. */
-export const composioSessionStorePath = () => path.join(path.dirname(INFRA_STORE_PATH), "composio-sessions.json");
-
-/** One helper for every message this module throws: an upstream body can echo a credential. */
-export function redactComposioMessage(message: string, secrets: (string | undefined)[]): string {
- let out = message;
- for (const secret of secrets) if (secret && secret.length >= 6) out = out.split(secret).join("[redacted]");
- return out;
-}
-
-function connectKeyRefusal(): IntegrationError {
- const error = new IntegrationError("composio_connect_key_wrong_provider", 409);
- error.message = COMPOSIO_CONNECT_KEY_MESSAGE;
- return error;
-}
-
-function headerMap(value: unknown): Record<string, string> {
- const raw = obj(value);
- const entries = Object.entries(raw);
- if (entries.length > MAX_HEADERS) throw new IntegrationError("invalid_composio_session_headers", 502);
- const headers: Record<string, string> = {};
- for (const [name, entry] of entries) {
- if (!HEADER_NAME.test(name) || typeof entry !== "string" || !entry || entry.length > 4096 || /[\r\n\0]/.test(entry)) {
- throw new IntegrationError("invalid_composio_session_headers", 502);
- }
- headers[name] = entry;
- }
- return headers;
-}
-
-/** Fail closed on a session URL pointing anywhere the session could not live. */
-function composioMcpUrl(raw: string): string {
- let href: string;
- try { href = normalizeMcpEndpoint(raw); } catch { throw new IntegrationError("invalid_composio_mcp_endpoint", 502); }
- if (!COMPOSIO_MCP_HOSTS.includes(new URL(href).hostname)) throw new IntegrationError("invalid_composio_mcp_host", 502);
- return href;
-}
-
/**
* POST a session for one end user. Server-side only: the caller's credential is sent
* in the same header `composioAuthHeader` already selects, and a ck_ key is refused
@@ -152,83 +79,6 @@ export async function createComposioSession(input: {
return { sessionId, mcpUrl, mcpHeaders };
}
-function parseStore(value: unknown): Store {
- const raw = obj(value);
- const bad = (): never => { throw new IntegrationError("invalid_composio_session_store"); };
- if (raw.version !== 1 || !raw.sessions || typeof raw.sessions !== "object" || Array.isArray(raw.sessions)) bad();
- const sessions: Record<string, StoredSession> = {};
- for (const [key, entry] of Object.entries(raw.sessions as Record<string, unknown>)) {
- const row = obj(entry);
- const keyParts = key.split(":");
- if (keyParts.length !== 2 || keyParts.some((part) => !KEY_PART.test(part))) bad();
- const { sessionId, instanceId, userUid, createdAt, expiresAt, mcpUrl: rawUrl } = row;
- const id = typeof sessionId === "string" && /^[A-Za-z0-9_-]{1,200}$/.test(sessionId) ? sessionId : bad();
- const instance = typeof instanceId === "string" ? instanceId : bad();
- const uid = typeof userUid === "string" ? userUid : bad();
- const created = Number.isSafeInteger(createdAt) ? createdAt as number : bad();
- let mcpUrl: string;
- try {
- mcpUrl = normalizeMcpEndpoint(String(rawUrl ?? ""));
- if (!COMPOSIO_MCP_HOSTS.includes(new URL(mcpUrl).hostname)) return bad();
- } catch { return bad(); }
- sessions[key] = {
- sessionId: id, mcpUrl, mcpHeaders: headerMap(row.mcpHeaders),
- instanceId: instance, userUid: uid, createdAt: created,
- ...(Number.isFinite(expiresAt) ? { expiresAt: Number(expiresAt) } : {}),
- };
- }
- return { version: 1, sessions };
-}
-
-export async function readComposioSessions(): Promise<Store> {
- const pinned = await pinSecurityStorePath(composioSessionStorePath());
- let handle;
- try {
- handle = await fs.open(pinned.file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
- const stat = await handle.stat();
- if (!stat.isFile() || stat.size < 1 || stat.size > MAX_STORE_BYTES || (stat.mode & 0o077) || stat.uid !== process.getuid?.()) throw new IntegrationError("unsafe_composio_session_store");
- return parseStore(JSON.parse(await handle.readFile("utf8")));
- } catch (error) {
- if ((error as NodeJS.ErrnoException).code === "ENOENT") return { version: 1, sessions: {} };
- if (error instanceof IntegrationError) throw error;
- throw new IntegrationError("invalid_composio_session_store");
- } finally { await handle?.close(); await pinned.directory.close(); }
-}
-
-async function writeComposioSessions(store: Store): Promise<void> {
- const pinned = await pinSecurityStorePath(composioSessionStorePath());
- const text = JSON.stringify(parseStore(store), null, 2) + "\n";
- try {
- if (Buffer.byteLength(text) > MAX_STORE_BYTES) throw new IntegrationError("composio_session_store_capacity", 409);
- const temporary = `${pinned.file}.${randomUUID()}.tmp`;
- try {
- const handle = await fs.open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
- try { await handle.writeFile(text); await handle.sync(); } finally { await handle.close(); }
- await fs.rename(temporary, pinned.file);
- } finally { await fs.unlink(temporary).catch(() => undefined); }
- await pinned.directory.sync();
- } finally { await pinned.directory.close(); }
-}
-
-const storeKey = (instanceId: string, userUid: string) => {
- if (!KEY_PART.test(instanceId) || !KEY_PART.test(userUid) || instanceId.includes(":") || userUid.includes(":")) throw new IntegrationError("invalid_composio_session_key");
- return `${instanceId}:${userUid}`;
-};
-
-/** Never returns another MSO user's session: the key is (instance, credential-owner uid). */
-export async function readComposioSession(instanceId: string, userUid: string): Promise<StoredSession | null> {
- const key = storeKey(instanceId, userUid);
- const row = (await readComposioSessions()).sessions[key];
- if (!row || row.instanceId !== instanceId || row.userUid !== userUid) return null;
- if (row.expiresAt !== undefined && row.expiresAt <= Date.now()) return null;
- return row;
-}
-
-export function composioRemoteUserId(instanceId: string, userUid: string): string {
- storeKey(instanceId, userUid);
- return `mso:${instanceId}:${userUid}`;
-}
-
/**
* Create-or-reuse for the credential owner selected server-side. Composio bills and
* rate-limits per session and the session MCP endpoint is per-session, so a stored