studiograph 1.3.48-next.26 → 1.3.48-next.261

package/dist/mcp/state-signer.js

@@ -0,0 +1,205 @@
+/**
+ * OAuth state signer
+ *
+ * Signs the `state` parameter on outbound OAuth flows so the server can prove,
+ * on callback/claim, that the userId + connector + origin it sees were minted
+ * by this instance — not forged by an attacker controlling a callback URL.
+ *
+ * Without integrity protection on `state`, an attacker who controls a
+ * `/api/oauth/callback/:name` or `/api/oauth/claim/:connector` URL can
+ * forge `{c, u, o}` to bind their own OAuth tokens against a victim's
+ * userId. This module closes that gap.
+ *
+ * Signing key is derived from the workspace master key via HKDF
+ * (info="studiograph-oauth-state-v1") so it's distinct from the AEAD key
+ * used for at-rest encryption — a leak of one doesn't compromise the other.
+ *
+ * The serialized state is a base64url-encoded JSON object:
+ *   { c, u, o, t, s }
+ * where `s` is the base64url HMAC-SHA256 over the canonical message
+ * (a JSON array of [c, u, o, t]). The OAuth broker continues to decode
+ * `c`, `u`, `o` from this JSON unchanged — adding `t` and `s` is forward-
+ * compatible.
+ */
+import { hkdfSync, createHmac, timingSafeEqual } from 'crypto';
+const HKDF_INFO = 'studiograph-oauth-state-v1';
+const HKDF_KEY_LENGTH = 32;
+const DEFAULT_MAX_AGE_MS = 10 * 60 * 1000;
+const FUTURE_SKEW_TOLERANCE_MS = 60_000;
+/**
+ * Derive a 32-byte signing key from the workspace master key. The `info`
+ * binding ensures this key is domain-separated from the AEAD key used to
+ * encrypt secrets at rest.
+ */
+export function deriveStateSigningKey(masterKey) {
+    if (masterKey.length !== 32) {
+        throw new Error('state-signer: master key must be 32 bytes');
+    }
+    const ikm = Buffer.from(masterKey);
+    // hkdfSync returns ArrayBuffer; wrap in Uint8Array view.
+    const derived = hkdfSync('sha256', ikm, Buffer.alloc(0), HKDF_INFO, HKDF_KEY_LENGTH);
+    return new Uint8Array(derived);
+}
+export function createOAuthStateSigner(key) {
+    if (key.length !== HKDF_KEY_LENGTH) {
+        throw new Error(`state-signer: signing key must be ${HKDF_KEY_LENGTH} bytes`);
+    }
+    const keyBuf = Buffer.from(key);
+    return {
+        sign({ connectorName, userId, origin }) {
+            if (typeof connectorName !== 'string' || connectorName.length === 0) {
+                throw new Error('state-signer: connectorName is required');
+            }
+            if (!Number.isInteger(userId)) {
+                throw new Error('state-signer: userId must be an integer');
+            }
+            if (typeof origin !== 'string' || origin.length === 0) {
+                throw new Error('state-signer: origin is required');
+            }
+            const t = Date.now();
+            const message = canonicalMessage({ c: connectorName, u: userId, o: origin, t });
+            const sig = createHmac('sha256', keyBuf).update(message).digest();
+            const blob = {
+                c: connectorName,
+                u: userId,
+                o: origin,
+                t,
+                s: sig.toString('base64url'),
+            };
+            return Buffer.from(JSON.stringify(blob)).toString('base64url');
+        },
+        verify(state, opts) {
+            try {
+                const decoded = Buffer.from(state, 'base64url').toString('utf-8');
+                const parsed = JSON.parse(decoded);
+                if (!parsed ||
+                    typeof parsed.c !== 'string' ||
+                    typeof parsed.u !== 'number' ||
+                    !Number.isInteger(parsed.u) ||
+                    typeof parsed.o !== 'string' ||
+                    typeof parsed.t !== 'number' ||
+                    !Number.isFinite(parsed.t) ||
+                    typeof parsed.s !== 'string') {
+                    return null;
+                }
+                const expected = createHmac('sha256', keyBuf)
+                    .update(canonicalMessage({ c: parsed.c, u: parsed.u, o: parsed.o, t: parsed.t }))
+                    .digest();
+                let provided;
+                try {
+                    provided = Buffer.from(parsed.s, 'base64url');
+                }
+                catch {
+                    return null;
+                }
+                if (expected.length !== provided.length)
+                    return null;
+                if (!timingSafeEqual(expected, provided))
+                    return null;
+                const now = Date.now();
+                const maxAge = opts?.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
+                if (now - parsed.t > maxAge)
+                    return null;
+                if (parsed.t - now > FUTURE_SKEW_TOLERANCE_MS)
+                    return null;
+                return {
+                    connectorName: parsed.c,
+                    userId: parsed.u,
+                    origin: parsed.o,
+                };
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}
+function canonicalMessage(p) {
+    return JSON.stringify([p.c, p.u, p.o, p.t]);
+}
+// ── Consent-binding signer (OAuth authorization server) ──
+//
+// The authorization server's `/oauth/authorize` GET renders a consent screen
+// whose hidden field carries the authorize parameters (client_id,
+// redirect_uri, code_challenge, scope, resource, userId, state). The POST
+// handler must trust those params came from a GET we rendered for *this*
+// logged-in user — without a signature an attacker could forge the form and
+// mint a code bound to a victim. We HMAC-sign an arbitrary JSON payload with a
+// timestamp, distinct from the outbound state signer above (different HKDF
+// `info`), and key it off the JWT secret so the whole AS depends only on a
+// value that is always present (no master key required, unlike state signing).
+const CONSENT_HKDF_INFO = 'studiograph-oauth-consent-v1';
+const CONSENT_DEFAULT_MAX_AGE_MS = 10 * 60 * 1000;
+/**
+ * Derive the consent signing key from the JWT secret via HKDF. Domain-separated
+ * from session JWTs (different mechanism entirely) and from the outbound state
+ * signer (different `info`). Keying off the JWT secret — rather than the master
+ * key — means the authorization server works on every boot, including
+ * non-encrypted/test boots where no master key is wired.
+ */
+export function deriveConsentSigningKey(jwtSecret) {
+    if (typeof jwtSecret !== 'string' || jwtSecret.length === 0) {
+        throw new Error('consent-signer: jwtSecret is required');
+    }
+    const derived = hkdfSync('sha256', Buffer.from(jwtSecret, 'utf-8'), Buffer.alloc(0), CONSENT_HKDF_INFO, HKDF_KEY_LENGTH);
+    return new Uint8Array(derived);
+}
+/**
+ * Generic HMAC payload signer: serializes `{ p: <payload>, t: <ts> }`, signs
+ * the canonical JSON with HMAC-SHA256, and base64url-encodes the blob. `verify`
+ * recomputes the HMAC with `timingSafeEqual`, enforces a max age, and rejects
+ * future-dated tokens. Returns the payload object on success, null otherwise.
+ */
+export function createConsentSigner(key) {
+    if (key.length !== HKDF_KEY_LENGTH) {
+        throw new Error(`consent-signer: signing key must be ${HKDF_KEY_LENGTH} bytes`);
+    }
+    const keyBuf = Buffer.from(key);
+    return {
+        sign(payload) {
+            const t = Date.now();
+            const message = JSON.stringify([payload, t]);
+            const sig = createHmac('sha256', keyBuf).update(message).digest();
+            const blob = { p: payload, t, s: sig.toString('base64url') };
+            return Buffer.from(JSON.stringify(blob)).toString('base64url');
+        },
+        verify(token, opts) {
+            try {
+                const parsed = JSON.parse(Buffer.from(token, 'base64url').toString('utf-8'));
+                if (!parsed ||
+                    typeof parsed.p !== 'object' ||
+                    parsed.p === null ||
+                    typeof parsed.t !== 'number' ||
+                    !Number.isFinite(parsed.t) ||
+                    typeof parsed.s !== 'string') {
+                    return null;
+                }
+                const expected = createHmac('sha256', keyBuf)
+                    .update(JSON.stringify([parsed.p, parsed.t]))
+                    .digest();
+                let provided;
+                try {
+                    provided = Buffer.from(parsed.s, 'base64url');
+                }
+                catch {
+                    return null;
+                }
+                if (expected.length !== provided.length)
+                    return null;
+                if (!timingSafeEqual(expected, provided))
+                    return null;
+                const now = Date.now();
+                const maxAge = opts?.maxAgeMs ?? CONSENT_DEFAULT_MAX_AGE_MS;
+                if (now - parsed.t > maxAge)
+                    return null;
+                if (parsed.t - now > FUTURE_SKEW_TOLERANCE_MS)
+                    return null;
+                return parsed.p;
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}
+//# sourceMappingURL=state-signer.js.map

package/dist/mcp/state-signer.js.map

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

package/dist/mcp/stdio-proxy.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Transparent stdio→HTTP MCP proxy (Increment 1 of the unified multi-peer
+ * editing model — see ~/.claude/plans/indexed-stirring-turtle.md).
+ *
+ * `studiograph mcp` no longer writes entities directly. Instead it presents an
+ * MCP server to Claude Desktop over stdio and forwards every `tools/list` and
+ * `tools/call` to an upstream MCP `Client`:
+ *
+ *   - REMOTE: a `StreamableHTTPClientTransport` to the running local server's
+ *     `/mcp` endpoint, so the write goes through BodyWriteCoordinator and merges
+ *     into any open live editor (this is the data-loss fix).
+ *   - LOCAL: an in-process server (InMemoryTransport) built lazily on demand,
+ *     used only when no live server is reachable — in which case there is no
+ *     open editor to clobber, so a direct write is safe.
+ *
+ * The upstream is re-selected on EVERY forwarded request (`probeServer`), which
+ * closes the "server started after Claude Desktop" window.
+ *
+ * FAIL-LOUD: if a request is routed to the remote and the transport throws, the
+ * error is surfaced to Claude Desktop and the remote client is marked stale so
+ * the next call re-probes. We NEVER silently retry the failed call against the
+ * local in-process server — that silent fallback is exactly the data-loss path
+ * this increment removes. A `probeServer` `fail` (the server rejected our token)
+ * is likewise surfaced, never downgraded to a local write.
+ *
+ * NOTE: stdout is owned by the JSON-RPC protocol — never console.log here. Use
+ * log.error (writes to stderr).
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { type ProbeDeps, type ProbeResult } from './server-discovery.js';
+export interface StdioProxyOptions {
+    workspacePath: string;
+    /** Per-user API token (or JWT) — sent only to a loopback server. */
+    token: string;
+    /** Builds + connects the in-process fallback client (lazy, cached). */
+    buildLocalClient: () => Promise<Client>;
+    /** Test seams. */
+    probeFn?: (workspacePath: string, token: string, deps?: ProbeDeps) => Promise<ProbeResult>;
+    buildRemoteClient?: (url: string, token: string) => Promise<Client>;
+}
+/** Connect an MCP Client to a running server's /mcp over Streamable HTTP. */
+export declare function createRemoteClient(url: string, token: string): Promise<Client>;
+export declare class StdioProxy {
+    private readonly opts;
+    private readonly probeFn;
+    private readonly buildRemoteClient;
+    private remote;
+    private localClient;
+    constructor(opts: StdioProxyOptions);
+    /**
+     * Probe + return the upstream client for this request. Throws an McpError on
+     * a `fail` probe (token rejected by a live server) — never falls back local.
+     */
+    private selectUpstream;
+    private markRemoteStale;
+    /** Forward a tools/list to the selected upstream. */
+    forwardListTools(params?: any): Promise<any>;
+    /** Forward a tools/call to the selected upstream. */
+    forwardCallTool(params: any): Promise<any>;
+    /** On a transport error against the remote, drop the cached client. */
+    private onUpstreamError;
+    /** Wire the two forwarders onto a low-level MCP Server. */
+    registerHandlers(server: Server): void;
+    /** Build the stdio-facing Server and connect it to Claude Desktop. */
+    start(): Promise<void>;
+}

package/dist/mcp/stdio-proxy.js

@@ -0,0 +1,149 @@
+/**
+ * Transparent stdio→HTTP MCP proxy (Increment 1 of the unified multi-peer
+ * editing model — see ~/.claude/plans/indexed-stirring-turtle.md).
+ *
+ * `studiograph mcp` no longer writes entities directly. Instead it presents an
+ * MCP server to Claude Desktop over stdio and forwards every `tools/list` and
+ * `tools/call` to an upstream MCP `Client`:
+ *
+ *   - REMOTE: a `StreamableHTTPClientTransport` to the running local server's
+ *     `/mcp` endpoint, so the write goes through BodyWriteCoordinator and merges
+ *     into any open live editor (this is the data-loss fix).
+ *   - LOCAL: an in-process server (InMemoryTransport) built lazily on demand,
+ *     used only when no live server is reachable — in which case there is no
+ *     open editor to clobber, so a direct write is safe.
+ *
+ * The upstream is re-selected on EVERY forwarded request (`probeServer`), which
+ * closes the "server started after Claude Desktop" window.
+ *
+ * FAIL-LOUD: if a request is routed to the remote and the transport throws, the
+ * error is surfaced to Claude Desktop and the remote client is marked stale so
+ * the next call re-probes. We NEVER silently retry the failed call against the
+ * local in-process server — that silent fallback is exactly the data-loss path
+ * this increment removes. A `probeServer` `fail` (the server rejected our token)
+ * is likewise surfaced, never downgraded to a local write.
+ *
+ * NOTE: stdout is owned by the JSON-RPC protocol — never console.log here. Use
+ * log.error (writes to stderr).
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, McpError, ErrorCode, } from '@modelcontextprotocol/sdk/types.js';
+import { probeServer } from './server-discovery.js';
+import { MCP_SERVER_INFO, MCP_INSTRUCTIONS } from './tools.js';
+import { log } from '../utils/log.js';
+/** Connect an MCP Client to a running server's /mcp over Streamable HTTP. */
+export async function createRemoteClient(url, token) {
+    const client = new Client({ name: 'studiograph-stdio-proxy', version: '1.0.0' });
+    const transport = new StreamableHTTPClientTransport(new URL(`${url}/mcp`), {
+        requestInit: { headers: { Authorization: `Bearer ${token}` } },
+    });
+    await client.connect(transport);
+    return client;
+}
+export class StdioProxy {
+    opts;
+    probeFn;
+    buildRemoteClient;
+    remote = null;
+    localClient = null;
+    constructor(opts) {
+        this.opts = opts;
+        this.probeFn = opts.probeFn ?? probeServer;
+        this.buildRemoteClient = opts.buildRemoteClient ?? createRemoteClient;
+    }
+    /**
+     * Probe + return the upstream client for this request. Throws an McpError on
+     * a `fail` probe (token rejected by a live server) — never falls back local.
+     */
+    async selectUpstream() {
+        const result = await this.probeFn(this.opts.workspacePath, this.opts.token);
+        if (result.mode === 'fail') {
+            this.markRemoteStale();
+            throw new McpError(ErrorCode.InternalError, `Studiograph server is running but rejected the token: ${result.reason}. ` +
+                `Check STUDIOGRAPH_MCP_TOKEN. (Not falling back to a local write — a live ` +
+                `editor may be open and a local write could overwrite unsaved edits.)`);
+        }
+        if (result.mode === 'remote') {
+            if (this.remote && this.remote.url === result.url)
+                return this.remote.client;
+            // URL changed or no cached remote — (re)connect.
+            this.markRemoteStale();
+            const client = await this.buildRemoteClient(result.url, this.opts.token);
+            this.remote = { client, url: result.url };
+            return client;
+        }
+        // local
+        if (!this.localClient) {
+            this.localClient = await this.opts.buildLocalClient();
+        }
+        return this.localClient;
+    }
+    markRemoteStale() {
+        if (this.remote) {
+            void this.remote.client.close().catch(() => { });
+            this.remote = null;
+        }
+    }
+    /** Forward a tools/list to the selected upstream. */
+    async forwardListTools(params) {
+        const client = await this.selectUpstream();
+        try {
+            return await client.listTools(params);
+        }
+        catch (err) {
+            this.onUpstreamError(err);
+            throw toMcpError(err);
+        }
+    }
+    /** Forward a tools/call to the selected upstream. */
+    async forwardCallTool(params) {
+        const client = await this.selectUpstream();
+        try {
+            // A tool that fails returns a normal result with `isError: true`; the SDK
+            // does NOT throw for that, so it forwards verbatim. A throw here is a
+            // transport/protocol failure — fail loud + re-probe next call.
+            return await client.callTool(params);
+        }
+        catch (err) {
+            this.onUpstreamError(err);
+            throw toMcpError(err);
+        }
+    }
+    /** On a transport error against the remote, drop the cached client. */
+    onUpstreamError(err) {
+        log.error(`[stdio-proxy] upstream call failed: ${err instanceof Error ? err.message : String(err)}`);
+        this.markRemoteStale();
+    }
+    /** Wire the two forwarders onto a low-level MCP Server. */
+    registerHandlers(server) {
+        server.setRequestHandler(ListToolsRequestSchema, async (req) => this.forwardListTools(req.params));
+        server.setRequestHandler(CallToolRequestSchema, async (req) => this.forwardCallTool(req.params));
+    }
+    /** Build the stdio-facing Server and connect it to Claude Desktop. */
+    async start() {
+        const server = new Server(MCP_SERVER_INFO, {
+            instructions: MCP_INSTRUCTIONS,
+            capabilities: { tools: {} },
+        });
+        this.registerHandlers(server);
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        log.error('Studiograph MCP stdio proxy ready');
+        process.on('SIGINT', async () => {
+            this.markRemoteStale();
+            await this.localClient?.close().catch(() => { });
+            await server.close();
+            process.exit(0);
+        });
+    }
+}
+/** Normalize an arbitrary upstream error into an McpError for the client. */
+function toMcpError(err) {
+    if (err instanceof McpError)
+        return err;
+    return new McpError(ErrorCode.InternalError, err instanceof Error ? err.message : String(err));
+}
+//# sourceMappingURL=stdio-proxy.js.map

package/dist/mcp/stdio-proxy.js.map

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

package/dist/mcp/tools.d.ts

@@ -5,11 +5,82 @@
  * methods — no new business logic. Results are returned as JSON text so the
  * MCP client (Claude Desktop) can process structured data.
  *
+ * Every tool enforces per-user access control via `services/access-control.ts`.
+ * Callers (the HTTP /mcp route, the stdio MCP server) must resolve a user
+ * identity before registering tools — `registerTools` requires a user in its
+ * `McpAccessContext` argument so there is no anonymous MCP path.
+ *
  * Note: `inputSchema` is cast to `any` at each call site because the MCP SDK's
  * ZodRawShapeCompat type does not accept ZodObject in TypeScript's strict mode.
  * Runtime schema validation is handled correctly by the SDK regardless.
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { WorkspaceManager } from '../core/workspace-manager.js';
-import type { AuthService } from '../services/auth-service.js';
-export declare function registerTools(server: McpServer, wm: WorkspaceManager, authService?: AuthService | null): void;
+import { type AuthService, type AuthUser } from '../services/auth-service.js';
+import type { WsHub } from '../server/ws-hub.js';
+import type { CommentService } from '../services/comment-service.js';
+import type { ArtifactSelectionStore } from '../services/artifact-selection-store.js';
+/**
+ * Server identity passed to `new McpServer(...)` on BOTH transports (stdio
+ * `src/mcp/server.ts` + HTTP `src/server/routes/mcp.ts`). Centralized so the
+ * two surfaces can never drift on name/version.
+ */
+export declare const MCP_SERVER_INFO: {
+    readonly name: "studiograph";
+    readonly version: "1.0.0";
+};
+/**
+ * Server-level `instructions` (MCP `ServerOptions.instructions`, surfaced in
+ * the `initialize` response). With Claude Code's tool-search/deferral on, this
+ * is what tells the client WHEN to search for Studiograph's tools — it loads
+ * even when individual tool schemas are deferred. Must be passed in McpServer's
+ * SECOND constructor arg (`new McpServer(MCP_SERVER_INFO, { instructions })`) —
+ * putting it in the serverInfo object silently drops it.
+ *
+ * Budget: Claude Code truncates server instructions at 2KB and front-loads
+ * matter most — keep this short and lead with category + when-to-reach-for-it.
+ */
+export declare const MCP_INSTRUCTIONS: string;
+/**
+ * Tools pinned against Claude Code's tool-search deferral via
+ * `_meta["anthropic/alwaysLoad"]=true` (see PIN_META). These are the handful an
+ * agent needs on essentially every turn, so they stay loaded even when the rest
+ * of the surface is deferred (verified: code.claude.com/docs/en/mcp.md, CC
+ * v2.1.121+). Keep this set SMALL — each pinned tool consumes upfront context.
+ * Exported so tests can assert the pin lands on exactly these tools.
+ */
+export declare const MCP_PINNED_TOOLS: readonly ["search_entities", "list_entities", "get_entity", "create_entity"];
+/** The resolved caller identity for an MCP session. */
+export interface McpAccessContext {
+    user: AuthUser;
+    /**
+     * Optional WebSocket hub. When supplied, entity-mutation tools
+     * (create_entity, update_entity) broadcast `entity_change` events so
+     * connected web clients refresh their views live — matching the HTTP
+     * routes in graph-api.ts. Absent in contexts that have no hub (stdio
+     * server, tests that don't care about live updates).
+     */
+    wsHub?: WsHub;
+    /**
+     * The user-set name on the api_tokens row that authenticated this session
+     * (e.g. "Cursor", "Claude Desktop"). Surfaced in `entity_change` and
+     * `agent_activity` events so other workspace users can see "Christian's
+     * Cursor created entry X" rather than a bare username.
+     */
+    apiTokenName?: string;
+    /**
+     * Optional CommentService. When supplied, generic entity tools dispatch
+     * `entity_type='comment'` reads through the virtual-entity adapter so
+     * agents see comments as first-class typed entities. Absent on stdio
+     * MCP contexts that don't construct a CommentService.
+     */
+    commentService?: CommentService;
+    /**
+     * Optional ArtifactSelectionStore (P4.4). When supplied (HTTP `/mcp`, same
+     * process as the web server), `get_current_selection` returns the frame the
+     * user has selected in the canvas. Absent on a standalone stdio MCP process —
+     * which has no in-memory UI selection — so the tool degrades to "no selection".
+     */
+    selectionStore?: ArtifactSelectionStore;
+}
+export declare function registerTools(server: McpServer, wm: WorkspaceManager, authService: AuthService, ctx: McpAccessContext): void;