studiograph 1.3.47 → 1.3.48-beta.1

package/dist/mcp/state-signer.js

@@ -0,0 +1,120 @@
+/**
+ * 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]);
+}
+//# 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/tools.d.ts

@@ -5,11 +5,44 @@
  * 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, AuthUser } from '../services/auth-service.js';
+import type { WsHub } from '../server/ws-hub.js';
+import type { CommentService } from '../services/comment-service.js';
+/** 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;
+}
+export declare function registerTools(server: McpServer, wm: WorkspaceManager, authService: AuthService, ctx: McpAccessContext): void;